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PREFACE 



MANUAL OBJECTIVES 

This manual is a guide to the use of RMS-11 in programs written in 
MACRO-11. It contains information necessary to writing MACRO-11 
programs and subprograms that use RMS-11 operations. 

INTENDED AUDIENCE 

This manual is intended for both the MACRO-11 programmer who wants to 
use RMS-11 operations and the high-level language programmer who wants 
to use RMS-11 operations in a MACRO-11 subprogram. 

STRUCTURE OF THIS DOCUMENT 

• Chapter 1, Introduction to RMS-11 with MACRO-11, introduces 
RMS-11 macros and symbols that are the interface between a 
MACRO-11 program and RMS-11 operation routines. 

• Chapter 2, RMS-11 Programming in MACRO-11, shows how to use 
RMS-11 macros and symbols in a MACRO-11 program. 

• Chapter 3, Processing Directories and Files, shows how to use 
directory and file operations to process directories and 
files. 

• Chapter 4, Processing Records and Blocks, shows how to use 
stream operations and either record or block operations to 
process records or blocks. 

• Chapter 5, Operation Macro Descriptions, describes in detail 
each RMS-11 operation macro, the control blocks it uses, the 
options you can specify in each control block field, and the 
values returned in control block fields. 

• Chapter 6, Control Block Fields, summarizes the use of each 
control block, field, value, and mask. 

• Chapter 7, Example Programs, contains programs and program 
segments that illustrate the uses of some major RMS-11 
features. 
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Appendix A, Completion Codes and Fatal Error Codes, lists 
RMS-11 completion symbols, values, and meanings. 

Appendix B, Assembly-Time Messages, lists the messages that 
RMS-11 macros can generate at assembly time. 

Appendix C, Macros That Declare Symbols and Other Macros, 
describes RMS-11 macros that declare other RMS-11 macros and 
define RMS-11 symbols. 

Appendix D, RMS-11 with Different Operating Systems, 
describes the differences among the behaviors of RMS-11 with 
various operating systems. 

The index includes a major entry for each RMS-11 macro, 
control block field mnemonic, keyword macro argument, and 
symbol family. 



ASSOCIATED DOCUMENTS 

R SX-11M/M-PLUS RMS-11: An Introduction introduces the major concepts 
of RMS-11, Introduces the RMS-11 operations, and defines key terms 
required for understanding RMS-11 capabilities and functions. You 
should read the introduction before proceeding to other manuals in the 
RMS-11 documentation set. 

The RSX-11M/M-PLUS RMS-11 User's Guide provides detailed information 
for both MACRO-11 and high-level language programmers on file and task 
design using RMS-11. 

The RSX-11M/M-PLUS RMS-11 Utilities manual is both a user and a 
reference document for all users, both programmers and nonprogrammers . 
It describes the RMS-11 utilities that are available for creating and 
maintaining RMS-11 files. 

In addition, the RSX-11M/M-PLUS RMS-11 Mini-Reference Insert is an 
easy-reference guide for users who are familiar with RMS-11 and its 
documentation. It summarizes the RMS-11 utilities and error codes. 

CONVENTIONS USED IN THIS DOCUMENT 

The following conventions are used in statement formats in this 
document: 

UPPERCASE Uppercase characters within a string indicate 
characters that you must include in the string; you 
can type the characters in uppercase or lowercase. 

lowercase Lowercase characters within a string indicate a 
user-selected variable; text following the 
statement format defines the syntax of the variable. 

[ ] Square brackets indicate that the enclosed string is 

optional user input. 

A horizontal ellipsis indicates that the immediately 
preceding optional string (enclosed in square 
brackets) may be repeated. 
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From: DES.TMP in examples of commands you enter and system 
responses, all output lines and prompting characters 
that the system prints or displays are shown in 
black letters. All the lines you type are shown in 
red letters. 

other A nonalphabetic character (except a square bracket 

or a period that is part of an ellipsis) indicates a 
character that you must include in the string. 

Numbers in this manual that give the values of RMS-11 symbols are in 
octal radix (base 8) unless otherwise indicated; all other numbers in 
this manual are in decimal radix (base 10) . 
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SUMMARY OF TECHNICAL CHANGES 

This revision contains the following technical changes: 

• The new operation macros $ENTER, SPARSE, $REMOVE, $RENAME, 
and $SEARCH are documented, along with the related NAM block 
fields FNB, RSA, RSL, and RSS. 

• The new facility for wildcard file specification is 
documented. 

• The extension of access sharing is documented, along with the 
related masks FB$UPI and FB$NIL for the SHR field of the FAB. 

• Random access to a sequential file with fixed-length records 
(similar to random access to a relative file) is documented. 

• The new print-format record-output handling is documented, 
along with the related symbol FB$PRN for the RAT field of the 
FAB. 

• The new sequential block access is documented; the previous 
block access (formerly called block I/O) is now called VBN 
access (virtual block number access) . 

• Block access can now be used to copy RMS-11 files without the 
need to modify the file's attributes manually. 

• The addition of the success handler facility for file 
operation macros ($CLOSE, $CREATE, $DISPLAY, $ERASE, $EXTEND, 
and $OPEN) is documented. 

• Increased device transparency for record access copy 
operations is supported. VFC and stream record formats are 
supported on unit-record devices. Relative and indexed files 
can be created for record access on nondisk devices, although 
they will appear as and be processed as sequential files 
there. 

• The obsolete RMS-11 initialization macros $INIT and $INITIF 
are no longer documented. These macros are now defined as 
no-ops in the RMS-11 macro library RMSMAC.MLB; their 
previous functions are no longer needed because RMS-11 is now 
self-initializing. However, programs that use the $INIT and 
$INITIF macros in their previous senses remain valid under 
RMS-11 Version 2.0. 
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SUMMARY OF TECHNICAL CHANGES 



Each XAB type now has a distinct name; 
new names: 



the following are the 



ALL block Area allocation XAB 

DAT block File date XAB 

KEY block File key XAB 

PRO block File protection XAB 

SUM block File summary XAB 

• The following symbol declaration macros are documented: 

FAB$BT Declare FAB value and mask symbols 

NAM$BT Declare NAM block value and mask symbols 

RAB$BT Declare RAB value and mask symbols 

XAB$BT Declare XAB value and mask symbols 

XBAOF$ Declare ALL block symbols 

XBDOF$ Declare DAT block symbols 

XBKOF$ Declare KEY block symbols 

XBPOF$ Declare PRO block symbols 

XBSOF$ Declare SUM block symbols 

• The description of each operation macro includes the use and 
meaning of each associated control block field. 



The value of each RMS-11 user symbol is documented, 



• The structure of each RMS-11 user 
documented. 



control 



block 



is 



• The FAB has a new LRL (longest record length) field for 
sequential files (corresponding to the VAX-11 RMS XAB LRL 
field) . 

• The date/time XABs have changed in size from 36 to 46 octal 
bytes. 

e For ANSI magtape, RMS-11 allows fixed- format records to be 
less than 18 bytes. 

• <CTRL/Z> and <ESC> are no longer recognized as record 
terminators for stream files; and <CTRL/Z> is no longer 
recognized as a file terminator for stream files. 

• RMS-11 now pads stream files with null characters to the high 
block of the file (not just to the end of the current block) . 
This means that RMS-11-created stream files can be read by 
programs that do not recognize the EOF value from the file 
header. 
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CHAPTER 1 
INTRODUCTION TO RMS- 11 WITH MACRO- 11 



RMS-11 macros and symbols provide access to RMS-11 operations from a 
MACRO-11 program. 



1.1 ADVANTAGES OF USING RMS-11 MACROS 

When you use RMS-11 operations from a high-level language, the 
language restricts your options for some operations. If you cannot 
accept these restrictions, you can write your program (or some of its 
modules) in MACRO-11; this allows you full access to RMS-11 options. 



1.2 RMS-11 MACROS AND SYMBOLS 

RMS-11 macros and symbols define the interface between a MACRO-11 
program and RMS-11 operation routines. Definitions for these macros 
and symbols are in the RMS-11 macro library, RMSMAC.MLB. 

RMS-11 macros allow your program to: 

• Call RMS-11 operations 

• Declare and manipulate control blocks, through which your 
program communicates with RMS-11 operation routines 

• Declare and manipulate space pools 

• Declare needed RMS-11 facilities 

• Extract (from the macro library RMSMAC.MLB) definitions for 
RMS-11 macros and symbols 

The following sections introduce RMS-11 macros and symbols. 
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1.2.1 Operations 



An RMS-11 operation macro calls a routine that performs an RMS-11 
operation. The name of an operation macro is the name of the 
corresponding operation, with a prefixed dollar sign ($) . The 
following are the RMS-11 operation macros: 



Directory 
Operation 
Macros 

$ENTER 
$PARSE 
$ REMOVE 
$RENAME 
$ SEARCH 



File 

Operation 

Macros 

$CLOSE 

$CREATE 

$DISPLAY 

$ERASE 

$EXTEND 

$OPEN 



Stream 

Operation 

Macros 

$CONNECT 

$DISCONNECT 

$FLUSH 

$FREE 

$NXTVOL 

$REWIND 

$WAIT 



Record 

Operation 

Macros 

$DELETE 

$FIND 

$GET 

$PUT 

$TRUNCATE 

$UPDATE 



Block 

Operation 

Macros 

$READ 

$SPACE 

$WRITE 



An RMS-11 operation returns a value called a completion code that 
indicates either a successful operation or an error. RMS-11 
completion symbols give names to these completion codes. 

When your program uses an RMS-11 operation macro to call an operation 
routine, it can specify completion handlers (one for a successful 
completion, one for an error completion) that RMS-11 calls when the 
operation completes. The RMS-11 completion-return macro ($RETURN) 
generates a proper return from a completion handler to the calling 
point in your program. 



1.2.2 Control Blocks and Fields 

Your program and RMS-11 operation routines communicate by passing data 
in blocks called control blocks. Each control block is divided into 
fields; each field has a 3-letter mnemonic name. 

An RMS-11 block-declaration macro allocates space for a control block 
-a^nd initializes fields containing the block length and block 
identifier. There is a block-declaration macro for each kind of 
control block. 

An RMS-11 field-initialization macro sets an initial value for a 
control block field at assembly time. There are field-initialization 
macros for most control block fields (those that you might reasonably 
want to initialize) . 



An RMS-11 field-access macro manipulates the value of a control block 
field during program execution. There are field-access macros for 
copying values to and from fields (SSTORE and $FETCH) , for comparing 
field values with other values ($COMPARE) , and for setting, clearing, 
and testing bits in fields ($SET, $OFF, and $TESTBITS) . 



RMS-11 code and mask symbols give names to the codes and bit masks 

used in many fields. This allows your program to determine the 

details of an RMS-11 operation without using the numeric values 
associated with those details. 



RMS-11 field-offset symbols give names to the locations of fields 
within their control blocks. Because RMS-11 field-initialization and 
field-access macros are based on field names, your program need not 
use field-offset symbols. 
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RMS-11 control blocks and their general uses are as follows: 

ALL (area allocation) block - contains information about a 
file area. 

DAT (file date) block - contains file dates and the file 
revision number. 

• FAB (file access block) - contains general information about a 
file and how a program will access it. 

• KEY (file key) block - contains information about a file index 
and its key. 

• NAM (file name) block - contains special information about the 
device, directory, and specification for the file, along with 
wildcarding information. 

• PRO (file protection) block - contains file owner and 
protection information. 

• RAB (record access block) - contains general information about 
a stream and a record or block, and how the program accesses 
the record or block. 

• SUM (file summary) block - contains the number of areas and 
indexes in the file, and a version number indicating the 
internal structure level of the file. 



1.2.3 Pools 

RMS-11 conserves space by dynamically allocating and deallocating 
space set aside in pools. RMS-11 pool-declaration macros allocate 
space for pools. 

An RMS-11 routine called the get-space routine handles pooled space. 
You can substitute your own get-space routine for the RMS-11 routine; 
you can use RMS-11 get-space-address macros to initialize the address 
of the get-space routine at assembly time (GSA$) , to change the 
address to that of a different routine during program^ execution 
($SETGSA) , and to return the address of the current routine during 
program execution ($GETGSA) . 



1.2.4 Facilities 

The RMS-11 facilities-declaration macro (ORG$) assists RMS-11 in 
determining exactly which routines your program needs during program 
execution. 



1.2.5 Macros That Declare Symbols and Other Macros 

To extract the definition of an RMS-11 macro from the macro library, 
your program must declare the macro in a .MCALL assembler directive. 

Many RMS-11 macros declare related macros and define related symbols; 
some RMS-11 macros have the sole purpose of declaring related macros 
and defining related symbols. Using these macros simplifies the job 
of declaring macros and defining symbols in your program. 
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For example, the FAB-declaration macro FAB$B declares FAB 
field-initialization macros and FAB offset, code, and mask symbols; 
the $FBCAL macro declares all directory and file operation macros; 
the $RMSTAT macro declares all completion symbols. 
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CHAPTER 2 
RMS- 11 PROGRAMMING 

To use RMS-11 operations in a MACRO-11 program, your program must: 

• Declare RMS-11 macros and symbols 

Before your program refers to an RMS-11 macro or symbol, it 
must extract its definition from the RMS-11 macro library. 
Section 2.1 shows how to declare macros and symbols. 

• Declare RMS-11 facilities 

To help RMS-11 decide which RMS-11 program modules are needed 
for your program, your program must declare some of the RMS-11 
operations that it uses. Section 2.2 shows how to declare 
RMS-11 facilities. 

• Declare and use pool space 

RMS-11 dynamically allocates and deallocates space for some of 
its requirements; this space is separated into five pools. 
Using RMS-11 pool-declaration macros, you specify the size of 
each pool. Section 2.3 shows how to declare pool space. 

• Declare and initialize control blocks 

Your program and RMS-11 operation routines communicate by 
passing data back and forth in control block fields. Using 
RMS-11 block-declaration and field-initialization macros, your 
program allocates space for control blocks and (optionally) 
assigns initial values for fields. Section 2.4 shows how to 
declare and initialize control blocks. 

• Use RMS-11 operations 

Your program uses RMS-11 operation routines to perform record 
management services; the routines return values that show the 
results of the operations. Your program uses RMS-11 operation 
macros to call these operation routines. Section 2.5 shows 
how to call RMS-11 operation routines and how to handle 
returns from the routines. 

Your program may also: 

Include completion handlers 

An RMS-11 operation routine returns either a success 
completion code or an error completion code. Your program can 
include special routines (called success handlers and error 
handlers) that operation routines call automatically when 
operations complete. Section 2.6 shows how to write 
completion handlers. 
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Use its own get-space routines 

RMS-11 uses a routine (called a get-space routine) to allocate 
and deallocate space. RMS-11 has a get-space routine, but you 
can also supply others of your own. Section 2.7 shows how to 
use get-space routines and how to write a get-space routine. 

Finally, you must: 

• Assemble the program 

When you assemble your program, it needs macro and symbol 
definitions from RMS-11; these are in a macro library, which 
your assembler command line must reference. RMS-11 macros 
detect some kinds of errors during assembly, and print 
messages that identify the errors. Section 2.8 shows how to 
assemble your program. 

• Build the task 

When you build your task, you must do one of the following: 

Use an RMS-11 resident library. 

Define an overlay structure for the task. RMS-11 offers 
several overlay definition (ODL) files from which you can 
select; you can also write your own ODL files. 

Include RMS-11 code in the task. 



2.1 DECLARING RMS-11 MACROS AND SYMBOLS 

Before your program refers to an RMS-11 macro or symbol, it must 
extract its definition from the RMS-11 macro library. 

Your program can use the .MCALL assembler directive to extract the 
definition of any RMS-11 macro (but not a symbol) from the macro 
library. For example, to extract the definition of the macro $CLOSE, 
use the .MCALL directive in the format: 

.MCALL $CLOSE ;Declare RMS-11 $CLOSE macro 

Your program can use RMS-11 macros to extract definitions for RMS-11 
symbols, and for some groups of other RMS-11 macros. Appendix C lists 
RMS-11 macros (with their arguments) that declare symbols and other 
macros . 



2.2 DECLARING RMS-11 FACILITIES 

To help RMS-11 decide which RMS-11 program modules your program needs, 
your program declares some of the operations that it uses. To d.q 
this, it uses the facilities-declaration macro ORG$ in the format: 

.MCALL ORG$ ; Declare ORG? macro 

ORG$ f ileorg [ ,<operation[ , operation] . . •>] 

where fileorg is a keyword indicating a file organization and each 
operation is a keyword indicating an operation that your program uses 
for a file of that organization. 
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A separate ORG$ macro is required for each different file organization 
that your program processes, except that no ORG? macro is required for 
an organization that will be processed using only directory operations 
and block access. 

The fileorg keyword argument to the ORG$ macro is one of the 
following: 

IDX Indexed file organization 
REL Relative file organization 
SEQ Sequential file organization 

Each operation argument to an ORG$ macro is one of the following: /*■ \ \ \ 

CRE CREATE operation \ r\*™>'~}*<^ 

<■"" DEL DELETE operation ^(ArC-*- i> > 

FIN FIND operation 

GET GET operation rr C!L{y^'x~J>^~ 

PUT PUT operation 

UPD UPDATE operation 

These are the only operations that your program explicitly declares 
with the ORG$ macro; , support for other operations is handled 
automatically. 

For example, suppose that your program: 

• Creates both sequential and indexed files 

• Uses FIND, GET, PUT, and UPDATE operations for sequential 
files 

• Uses FIND, GET, PUT, and DELETE operations for indexed files 
Then the proper ORG$ macros are: 

ORG$ SEQ,<FIN,GET,PUT,UPD> ;Declare FIND, GET, PUT, and UPDATE 

; operations for sequential files 

ORG$ IDX,<FIN,GET,PUT,DEL> ;Declare FIND, GET, PUT, and DELETE 

; operations for indexed files 

The results of ORG$ macros are additive. For example, if one portion 
of your program specifies 

ORG$ SEQ,<GET,PUT> 
and another specifies 

ORG$ SEQ,<GET,UPD> 
then the effect is the same as specifying 

ORG$ SEQ,<GET,PUT,UPD> 

Note also that all ORG$ macros must occur in modules that are 

contained in the root segment of your task (not overlaid) . Use of 

ORG$ macros is optional in tasks linked with an RMS-11 memory-resident 
library. 
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2.3 DECLARING AND USING POOL SPACE 

RMS-11 dynamically allocates and deallocates space for some of its 
requirements; this space is separated into five pools: 

Internal FAB and index descriptor block (IFAB/IDB) pool 

• Internal RAB (IRAB) pool 

• Key buffer pool 

• I/O buffer pool 

• Buffer descriptor block (BDB) pool 

RMS-11 has a get-space routine that manages these pools, and that 
allocates and deallocates space to meet the needs of RMS-11 
operations; however, you can supply other get-space routines and 
direct RMS-11 to use a different routine (and, optionally, different 
pools) instead of its own. 

If you use only the RMS-11 get-space routine, declare pool space using 
the pool-declaration macros described below. If you us'e your own 
get-space routine, read Section 2.7; it shows how to write the 
routine, and how to manage the pools. 

To declare space for pools, use pool-declaration macros in the format: 



POOL$B 

P$FAB fabcount 

P$IDX indexcount 

P$RAB rabcount 



;Begin pool declarations 
; Space for IFABs in IFAB/IDB pool 
: Space for IDBs in IFAB/IDB pool 
[Space for IRABs for sequential 
and relative files and for 
block-accessed indexed files 
in IRAB pool 
P$RABX rabxcount,keysize,keychanges ;Space for IRABs for 

record-accessed indexed 
files in IRAB pool, and 
space for key buffers in 
key buffer pool 
P$BUF bufcount ;Space for I/O buffers in I/O 

buffer pool 

P$BDB bdbcount ;Space for BDBs in BDB pool 

POOL$E ;End pool declarations 

If your program uses multiple pool declarations, the results are 
cumulative. 

The following sections show how to compute the values of arguments to 
the pool-declaration macros. 
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2.3.1 Internal FAB and Index Descriptor Block Pool 

Internal FABs (IFABs) and index descriptor blocks (IDBs) are the same 
size and so share a pool (the IFAB/IDB pool) . The total size of the 
pool is the sum of the following: 

• The largest number of IFABs that your program uses at the same 
time, times 48 bytes. Specify this largest number of IFABs 
(not multiplied by 48) as the fabcount argument to the P$FAB 

macro. 

A directory operation uses one IFAB, which is returned to the 
pool before the operation completes. 

A CREATE or OPEN operation uses one IFAB, which is committed 
while the file is open; a CLOSE operation releases the IFAB. 
A DISPLAY or EXTEND operation uses no new IFABs; it uses the 
IFAB already committed to the open file. An ERASE operation 
uses one IFAB, which is released before the operation 
completes. 

• The largest number of IDBs that your program uses at the same 
time, times 48 bytes. Specify this largest number of IDBs 
(not multiplied by 48) as the indexcount argument to the P$IDX 

macro. 

Your program uses one IDB for each index of each indexed file 
opened for record access (rather than block access) . The IDBs 
for an indexed file are committed when the file is opened (by 
a CREATE or OPEN operation) and are released when the file is 
closed (by a CLOSE operation) . 



2.3.2 Internal RAB Pool 

Internal record access blocks (IRABs) have a separate pool. The size 
of the IRAB pool is the largest number of streams that your program 
will have connected at the same time, times the size of an IRAB (32 

bytes) . 

Specify the largest number of streams connected to sequential files, 
relative files, and block-access indexed files (not multiplied by 32) 
as the rabcount argument to the P$RAB macro. Specify the largest 
number of streams connected to record-access indexed files as the 
rabxcount argument to the P$RABX macro. 

If the sum of the rabcount and rabxcount arguments is larger than the 
largest number of streams that will ever be connected simultaneously, 
you may deduct the excess from the rabcount argument that you specify. 

An IRAB is committed when a stream is connected and is released when 
the stream is disconnected or the file is closed (using the associated 
FAB) . 
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2.3.3 Key Buffer Pool 

Key buffers have a separate pool. (These key buffers are different 
from those specified by the KBF and KSZ fields of the RAB.) 

Each time a stream is connected to an indexed file (for record 

access) , the CONNECT operation requests space from the key buffer 

pool; the space is released when the stream is disconnected or the 
file is closed. 

Compute the size (in bytes) of the request that the CONNECT operation 
makes as follows: 

1. Begin with the size of the largest key for the file. 

2. Multiply by 2. 

3. Add the number of alternate keys for the file that are 
allowed to change during updating. 

4. Add 1. 

5. Round up (if necessary) to a multiple of 4. 

If your program performs complex sequences of CONNECT and DISCONNECT 
(or CLOSE) operations for record-access indexed files with different 
key sizes, the key buffer pool may become fragmented (and therefore 
contain unusable space) . In this case, the total size of the key 
buffer pool should be larger than the sum of the requirements for each 
connected stream. 

Each P$RABX macro that your program uses (in the format P$RABX 
rabxcount,keysize,keychanges) allocates a number of bytes for the key 
buffer pool that is equal to 

(rabxcount) x ((keysize * 2) + keychanges + 1) 

The expression ((keysize * 2) + keychanges +1) is rounded up (if 
necessary) to a multiple of 4. 

You can use P$RABX macros to precisely tailor the size of the key 
buffer pool, or to provide extra space against possible fragmentation 
problems. A good compromise is to choose the arguments to the P$RABX 
macro as follows: 

• Choose rabxcount as the largest number of streams that will be 
connected to record-access indexed files. 

• Choose keysize as the largest key in any file that will be 
processed. 

• Choose keychanges as the maximum number of changeable keys in 
any file that will be processed. 



2.3.4 I/O Buffer Pool 

The I/O buffers for RMS-11 operations come either from the central 

buffer pool or from a private buffer pool. (These are RMS-11 internal 

I/O buffers, and are different from the I/O buffers specified in the 
RBF, RSZ, UBF, and USZ fields of the RAB.) 
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Your program can specify a private buffer pool for a directory or file 

operation (except CLOSE, DISPLAY, or EXTEND). If your program does 

not specify a private buffer pool, these operations use the central 
buffer pool. 

All other operations that require I/O buffers use the same pool as the 
CREATE or OPEN operation that opened the file. 

The minimum size of the central I/O buffer pool is the sum of the 
sizes of the I/O buffers that your program will need from it at the 
same time (ignoring I/O buffers supplied from private buffer pools) . 
Specify the size (in bytes) of the central buffer pool as the 
iopoolsize argument to the P$BUF macro. 

Specify the size (in bytes) of a private buffer pool for an operation 
in the 1-word BPS field of the FAB and the address in the 1-word BPA 
field of the FAB. If your program specifies a private buffer pool for 
a CREATE or OPEN operation, the entire pool is reserved for and 
managed by that file until the file is closed. 

Your program needs space from buffer pools for the following: 

• One 512-byte I/O buffer for any directory or file operation 
(except CLOSE, DISPLAY, or EXTEND). This space is released 
before the operation completes. 

• One 512-byte I/O buffer for a DISPLAY or EXTEND operation for 
a record-access relative or indexed file; the space is 
returned when the operation completes. 

• I/O buffers for a CONNECT operation: 

One I/O buffer for a record-access stream connected to a 
sequential disk file. The I/O buffer uses 512 bytes times 
the multiblock count for the stream. 

One I/O buffer for a record-access stream connected to a 
sequential magtape file. The number of bytes in the I/O 
buffer is the block size for the file, rounded up (if 
necessary) to a multiple of 4 bytes. 

- One I/O buffer for a record-access stream connected to a 
file on a unit-record device. The number of bytes in the 
I/O buffer is equal to the default block size for the 
device, rounded up (if necessary) to a multiple of 4 bytes. 

One or more I/O buffers for a stream connected to a 
relative file. Each I/O buffer uses 512 bytes times the 
bucket size for the file. If you use the multibuffer count 
to specify additional buffers, the requirement increases 
accordingly. 

- Two or more I/O buffers for a stream connected to an 
indexed file. Each I/O buffer uses 512 bytes times the 
bucket size for the file. If you use the multibuffer count 
to specify additional buffers, the requirement increases 
accordingly. 

I/O buffers for a connected stream are retained until the 
stream is disconnected by a DISCONNECT or CLOSE operation. 
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If your program uses the I/O buffer pool for complex sequences of 
operations that use I/O buffers for different files, the pool may 
become fragmented. In that case, you may want to either allocate 
extra space in the I/O buffer pool, or limit fragmentation through the 
judicious use of private buffer pools. 



2.3.5 Buffer Descriptor Block Pool 

Your program requires one 20-byte buffer descriptor block (BDB) for 
each I/O buffer (whether from the central or a private pool) that it 
uses at the same time; these BDBs are allocated and returned at the 
same time as their associated I/O buffers. (I/O buffer requirements 
are described in the previous section.) 

In addition, a block-access stream (for any file) or a record-access 
stream that will write to a relative file requires an additional BDB; 
a record-access stream that will write to an indexed file requires two 
additional BDBs. These BDBs are returned when the stream is 
disconnected (or the file is closed) . 

An EXTEND operation for a record-access relative or indexed file also 
requires an additional BDB, which is returned when the operation 
completes . 

Therefore the size of the BDB pool is the largest number of BDBs 
required at any one time, times 20 bytes. Specify this largest number 
of BDBs (not multiplied by 20) as the bdbcount argument to the P$BDB 
macro. 



2.4 DECLARING AND INITIALIZING CONTROL BLOCKS 

Your program and RMS-11 operation routines communicate by passing data 
back and forth in control block fields. Using RMS-11 
block-declaration and field-initialization macros, you allocate space 
for control blocks and (optionally) assign initial values for fields. 



To declare a control block and initialize its fields, 
block-declaration and field-initialization macros as follows: 



use 



Make sure the control block 
.EVEN directive: 



is word-aligned by using the 



.EVEN 



;Word-align block 



Specify a label so that your program can 
to the address of the control block. 



refer symbolically 



label i 



Begin the block declaration with one of the following macros; 



FAB$B 
NAM$B 
RAB$B 



XAB$B 
XAB$B 
XAB$B 
XAB$B 
XAB$B 



SYN 



RAB$B ASYN 



XB$ALL 
XB$DAT 
XB$KEY 
XB$PRO 
XB$SUM 



;Begin FAB declaration 

;Begin NAM block declaration 

;Begin RAB declaration for 

; synchronous RAB 

;Begin RAB declaration for 

; asynchronous RAB 

;Begin ALL block declaration 

;Begin DAT block declaration 

;Begin KEY block declaration 

;Begin PRO block declaration 

;Begin SUM block declaration 



2-8 



RMS-11 PROGRAMMING 



4. Initialize (optionally) fields with field-initialization 
macros of one of the forms: 

F$fld arg ; Initialize FAB field 

N$fld arg ;Initialize NAM block field 

R$fld arg ;Initialize RAB field 

X$fld arg ;Initialize XAB field 

In each of these forms, fid is the mnemonic for a field in 
the control block; arg is an argument suitable for the value 
of the field. Chapter 6 describes field-initialization 
macros and their arguments. 

5. End the block declaration with one of the following macros: 

FAB$E ;End FAB declaration 

NAM$E ;End NAM block declaration 

RAB$E ;End RAB declaration 

XAB$E ;End XAB declaration 



2.5 USING RMS-11 OPERATIONS 

Your program uses RMS-11 operation routines to perform record 
management services. Using RMS-11 operation macros, you call these 
operation routines. The routines return values in control block 
fields that show the results of the operations. 

To use RMS-11 operation routines, your program must: 

• Set up control block fields 

The values that your program places in control block fields 
specify the details of the service you want from the RMS-11 
operation routine. Section 2.5.1 shows how to set up control 
block fields. 

• Chain control blocks 

Some RMS-11 operation routines (stream, record, and block 
operation routines) read only RAB fields; others (directory 
and file operation routines) read FAB fields and, if your 
program supplies them, fields in NAM blocks and XABs . Your 
program chains these blocks (using address pointers) so that 
the operatiori routine can find them. Section 2.5.2 shows how 
to chain control blocks. 

• Call operation routines 

You use RMS-11 operation macros to call RMS-11 operation 
routines. Section 2.5.3 shows how to call operation routines. 

• Handle returns 

Section 2.5.4 shows how to handle returns from operation 
routines . 

Examine returned values 

When an RMS-11 operation routine completes its execution, it 
has placed values in control block fields that show the 
results of the operation. Your program should examine these 
values to determine the results. Section 2.5.5 shows how to 
examine returned values . 
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2.5.1 Setting Op Control Block Fields 

The values that your program places into control block fields specify 
the details of the service you want from the RMS-11 operation routine. 
The description of each operation macro in Chapter 5 discusses the 
control block fields that are read by that operation. 

Three RMS-11 field-access macros help you place values into control 
block fields: 

• $STORE places a specified value into a field. 

• $SET sets bits in a field. 

• $OFF clears bits in a field. 



2.5.1.1 $STORE Macro - Use the $STORE macro to copy a value from a 
specified location to a control block field. The format for the 
$STORE macro is: 

$STORE src,fld,reg 

where src is a an address in memory; fid is a field mnemonic; and 
reg is a general purpose register (RO through R5) containing the 
address of the control block. 

The $STORE macro looks up the size of the destination field, so that 
it can copy the correct number of bytes or words. If the source is a 
register and the destination is a 1-byte field, then the low byte of 
the register is copied; if the source is a register and the 
destination is a multiword field, then the contents of the specified 
register and following registers are copied. 

The $STORE macro generates an error during assembly if you use an 
illegal address mode for the source. For multiword fields, illegal 
address modes are autoincrement deferred, autodecrement deferred, and 
indexed deferred. 

It is also illegal to specify the program counter (PC) as the source 
or to specify a register as source in such a way that the source 
overlaps the register that contains the control block address. 

At execution time, the $STORE macro copies the contents of the 

specified location to the control block field. The number of bytes or 

words copied is the same as the field size for the mnemonic. Chapter 
6 gives the size of each control block field. 

For example, suppose that you want to specify indexed file 
organization in the FAB for a file, and suppose that the address of 
that FAB is stored in register R2. Then the proper macro is: 

$STORE #FB$IDX,ORG,R2 ;Indexed file organization 

Suppose that you want to chain a NAM block whose label is NAMBLK to 
the same FAB. Then the proper macro is: 

$STORE #NAMBLK,NAM,R2 ;Chain NAM block 
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Suppose that you want to set the allocation quantity (ALQ field) of 
the same FAB to the value stored in a location labeled ALQVAL. Then 
the proper macro is: 

$STORE ALQVAL, ALQ, R2 ;Load allocation quantity 

and (because ALQ is a 2-word field) two words are copied from ALQVAL 
to the ALQ field. 



2.5.1.2 $SET Macro - Use the $SET macro to set bits in a 1-byte or 
1-word control block field. The $SET macro logically ORs a given mask 
into the control block field. Therefore for each bit set in the mask, 
the $SET macro sets the corresponding bit in the field; the other 
bits are not changed. 

Note that you use the $SET macro only if you want to leave some bits 
in a field undisturbed; if you want to set specified bits and clear 
all others, use the $STORE macro. 

The format for the $SET macro is: 

$SET mask, fid, reg 

where mask is an address in memory containing bits to be set; fid is 
the mnemonic for a control block field; and reg is a general purpose 
register (RO through R5) containing the address of the control block. 

If the field is not a 1-byte or 1-word field, the $SET macro generates 
an error during assembly. 

RMS-11 has symbols for masks for each bit-oriented control block 
field. Therefore your program can use these symbols instead of 
numerical values. 

For example, suppose you want to specify rewind-on-close in the FAB 
for a file, but do not want to disturb other bits in the FOP field of 
the FAB; suppose also that the address of the FAB is in register R2. 
Then the proper macro is: 

$SET #FB$RWC,F0P,R2 ; Rewind-on-close 

As another example, suppose you want to specify key-duplicates-allowed 
and key-changes-allowed for an index, but do not want to disturb other 
bits in the FLG field of the KEY block; suppose also that the address 
of the KEY block is in register R4 . Then the proper macro is: 

$SET #XB$DUP!XB$CHG,FLG,R4 ;Allow key duplicates and changes 



2.5.1.3 $OFF Macro - Use the $OFF macro to clear bits in a 1-byte or 
1-word control block field. The $OFF macro logically ANDs the l's 
complement of a given mask into the control block field. Therefore 
for each bit set in the mask, it clears the corresponding bit in the 
field; the other bits are not changed. 

Note that you use the $OFF macro only if you want to leave some bits 
in a field undisturbed; if you want to clear the entire field, use 
the $STORE macro (with a source value of #0) . 
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The format for the $OFF macro is: 

$OFF mask, fid, reg 

where mask is an address in memory containing bits to be cleared; fid 
is the mnemonic for a control block field; and reg is a general 
purpose register (RO through R5) containing the address of the control 
block. 

If the field is not a 1-byte or 1-word field, the $OFF macro generates 
an error during assembly. 

RMS-11 has symbols for masks for each bit-oriented control block 
field. Therefore your program can use these symbols instead of 
numerical values. 

For example, suppose you want to specify no-rewind-on-close in the FAB 
for a file, but do not want to disturb other bits in the FOP field of 
the FAB; suppose also that the address of the FAB is in register R2. 
Then the proper macro is: 



$OFF #FB$RWC,F0P,R2 



;No rewind-on-close 



As another example, suppose you want to specify 
no-key-duplicates-allowed and no-key-changes-allowed for an index, but 
do not want to disturb other bits in the FLG field of the KEY block; 
suppose also that the address of the KEY block is in register R4 . 
Then the proper macro is: 



$OFF #XB$DUP!XB$CHG,FLG,R4 



;No key duplicates or changes 



2.5.2 Chaining Control Blocks 

An RMS-11 directory operation or file operation uses at least one FAB; 
you specify FABs in the operation macros that call the operation 
routines. 

For some directory operations, a NAM block is required; it is 

optional for other directory operations and for file operations. You 

specify a NAM block and XABs for an operation by chaining them to the 
FAB for the operation. 



2.5.2.1 Chaining a NAM Block to a FAB - Specify the NAM block 
associated with a FAB by placing its address in the 1-word NAM field 
of the FAB. 



2.5.2.2 Chaining XABs to a FAB - Specify the XABs associated with a 
FAB by placing the address of the first XAB in the 1-word XAB field of 
the FAB; in each XAB, specify the address of the next XAB in the 
chain in the 1-word NXT field of the XAB; in the last XAB in the 
chain, specify in the NXT field. 

Follow these rules in ordering XABs in a chain: 

Place ALL blocks together in the chain. Each ALL block is 
"numbered" by the value in the 1-byte AID field of the ALL 
block; chain ALL blocks so that these numbers are in 
ascending order. For the CREATE operation, begin with and 



do not skip numbers in the ascending sequence; 
operations, you can skip numbers in the sequence. 



for other 
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Place no more than one DAT block in the chain. 

Place KEY blocks together in the chain. Each KEY block is 
"numbered" by the value in the 1-byte REF field of the KEY 
block; chain KEY blocks so that these numbers are in 
ascending order. For the CREATE operation, begin with and 
do not skip numbers in the ascending sequence; for other 
operations, you can skip numbers in the sequence. 

Place no more than one PRO block in the chain. 

Place no more than one SUM block in the chain. 



2.5.2.3 Chaining a FAB to a RAB (CONNECT Operation) - The CONNECT 

operation creates a stream for a file. A FAB specifies the file; a 

RAB specifies the stream. Specify the address of the FAB for the file 

in the 1-word FAB field of the RAB for the stream. 



2.5.3 Calling Operation Routines 

Use RMS-11 operation macros to call operation routines. You can 
specify arguments for the operation routine either by giving them as 
arguments to the operation macro, or by placing them in an argument 
block in memory. 



2.5.3.1 Call with Macro Arguments - Call an operation routine (except 
RENAME) using an operation macro with arguments in the format: 

$macroname blkaddr [ , [erraddr] [ ,sucaddr] ] 

where $macroname is the name of an operation macro (except $RENAME) ; 

blkaddr is the address of a FAB (for a directory or file operation) or 

a RAB (for a stream, record, or block operation); erraddr is the 

address of an error handler for the operation; and sucaddr is the 
address of a success handler for the operation. 

For example, if you want to open a file using a FAB at address INFAB 
and want to use a success handler at address SUCCES, the macro call 
would be: 



$OPEN # INFAB, ,#SUCCES 

Call the RENAME operation using 
arguments in the format: 



the $RENAME operation macro with 



$RENAME oldfabaddr , [erraddr] , [sucaddr] ,newfabaddr 

where oldfabaddr is the address of a FAB for the old file 
specification; erraddr is the address of an error handler for the 
operation; sucaddr is the address of a success handler for the 
operation; and newfabaddr is the address of a FAB for the new file 
specification. 
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2.5.3.2 Call with Arguments in Memory - To call an operation routine 
using an operation macro with arguments in an argument block in 
memory, omit the arguments to the macro, store the address of the 
argument block in register R5, and store the argument block in memory 
as follows: 



ARGUMENT COUNT 



ADDRESS OF FAB OR RAB 



ADDRESS OF ERROR HANDLER (OPTIONAL) 



ADDRESS OF SUCCESS HANDLER (OPTIONAL) 



ADDRESS OF NEW FAB (RENAME ONLY) 




2 
4 
6 
10 



ZK-1097-82 



The argument count is 4 for a RENAME operation; otherwise it is one 
of the following: 



• 1 - no completion handlers 

• 2 - error handler, but no success handler 

• 3 - success handler 



If the operation has no error handler, but either has a success 
handler or the operation is RENAME, specify -1 as the address of the 
error handler; if the operation has no success handler, but the 
operation is RENAME, specify -1 as the address of the success handler. 



2.5.4 Handling Returns 

An RMS-11 file or directory operation returns a completion status code 
in the 1-word STS field of the FAB and, for some completions, a 
completion status value in the 1-word STV field of the FAB. 

An RMS-11 stream, record, or block operation returns a completion 
status code in the 1-word STS field of the RAB and, for some 
completions, a completion status value in the 1-word STV field of the 

RAB. 

Appendix A lists completion codes. 

Your program should examine the STS field contents to determine 
whether the operation was successful; even if the operation returned 
an error completion, your program may be able to handle the error and 
recover. 

The program can handle the return (based on the completion code) 
either in the code that immediately follows the operation macro, or in 
special routines (called completion handlers) that the operation can 
call. Section 2.6 shows how to write completion handlers. 



2-14 



RMS-11 PROGRAMMING 

There are two kinds of fatal RMS-11 errors: 

If the FAB or RAB address you specify is not the address of a 
valid and idle FAB or RAB, or if the argument block you 
provide is invalid, RMS-11 cannot return values, even in the 
STS field. RMS-11 issues a BPT instruction, leaving status 
information in the following registers: 

RO: RMS-11 fatal error code 

Rl: Stack pointer (at time of entry to RMS-11 routine) 

R2: Program counter (entry return same as @R1) 

R3 : Address of system impure area 

• If RMS-11 detects the corruption of memory-resident data 
structures, or if it detects inconsistent internal states, it 
cannot proceed with its operations. In these cases, RMS-11 
halts execution with a BPT instruction; if it can identify 
the error, RMS-11 leaves an error completion in RO. 

Appendix A lists the symbols and values for RMS-11 fatal error codes. 



2.5.5 Examining Returned Values 

When an RMS-11 operation routine completes its execution, it has 
placed values in control block fields that show the results of the 
operation. Your program should examine these values to determine the 
results. The description of each operation macro in Chapter 6 
discusses the control block fields that return values for that 
operation. 

Three RMS-11 field-access macros help you examine values in control 
block fields: 

• $FETCH copies a value from a field to a specified location. 

• $COMPARE compares a field value to a specified value. 

• $TESTBITS determines whether specified bits in a field are 
set. 



2.5.5.1 $FETCH Macro - Use the $FETCH macro to copy a value from a 
control block field to a specified location. The format for the 
$FETCH macro is : 

$FETCH dst,fld,reg 

where dst is an address in memory; fid is the mnemonic for a control 
block field; and reg is a general purpose register (RO through R5) 
containing the address of the control block. 

The $FETCH macro looks up the size of the source field, so that it can 
copy the correct number of bytes or words. If the destination is a 
register and the source is a 1-byte field, then the byte is copied to 
the low byte of the register and the high byte is cleared. if the 
destination is a register and the source is a multiword field, then 
the multiword field is copied to the specified register and following 
registers . 



2-15 



RMS- 11 PROGRAMMING 

The $FETCH macro generates an error during assembly if you use an 
illegal address mode for the destination. For multiword fields, 
illegal address modes are autoincrement deferred, autodecrement 
deferred, and indexed deferred. Immediate mode is illegal for $FETCH, 
regardless of field size. 

It is also illegal to use the program counter (PC) as the destination 

or to specify a register for the destination in such a way that the 

destination overlaps the register that contains the control block 
address. 

At execution time, the $FETCH macro copies the contents of the control 
block field to the specified location. The number of bytes or words 
copied is the same as the field size for the mnemonic. Chapter 6 
gives the size of each control block field. 

As an example of the use of the $FETCH macro, suppose that you want to 
fetch the allocation quantity (ALQ field) from a FAB to a location 
labeled ALQSAV, and suppose also that the address of the FAB is in 
register R3 . Then the proper macro is: 

$FETCH ALQSAV, ALQ, R3 ;Save allocation quantity 

and two words are copied from the ALQ field to memory beginning at 
ALQSAV. 



2.5.5.2 $COMPARE Macro - Use the $COMPARE macro to compare the 
contents of a 1-byte or 1-word control block field with a specified 
value. The format for the $COMPARE macro is: 

$COMPARE src,fld,reg 

where src is an address in memory; fid is the mnemonic for a control 
block field; and reg is a general purpose register (RO through R5) 
containing the address of the control block. 

If the given field is not a 1-byte or 1-word field, the $COMPARE macro 
generates an error during assembly. 

At execution time, the $COMPARE macro executes a machine instruction 
that compares the source value and the field contents. The 
instruction executed depends on the size of the specified field and on 
the specified source: 

• TSTB for a 1-byte field and the source #0 

• TST for a 1-word field and the source #0 

• CMPB for a 1-byte field and a source other than #0 

• CMP for a 1-word field and a source other than #0 

Chapter 6 gives the size of each control block field. 

For example, suppose that you want to compare the value in the RSZ 

field of a RAB with a value stored in a location labeled RSZSAV, and 

suppose also that the address of the RAB is stored in register R2. 
Then the proper macro is: 

$COMPARE RSZSAV, RSZ, R2 ;Compare record size 
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Suppose that you want to compare the same RSZ field to the value of a 
symbol, RECSIZ. Then the proper macro is: 

$COMPARE #RECSIZ,RSZ,R2 ;Compare record size 



2.5.5.3 $TESTBITS Macro - Use the $TESTBITS macro to test the values 
of bits in a 1-byte or 1-word control block field. Chapter 6 gives 
the size of each control block field. The format for the $TESTBITS 
macro is: 

$TESTBITS mask,fld,reg 

where mask is an address in memory containing bits to be tested; fid 
is the mnemonic for a control block field; and reg is a general 
purpose register (RO through R5) containing the address of the control 
block . 

If the given field is not a 1-byte or 1-word field, the $TESTBITS 
macro generates an error during assembly. 

At execution time, the $TESTBITS macro executes a machine instruction 
that tests the bits specified in the mask. The instruction executed 
depends on the size of the specified field: 

• BITB for a 1-byte field 

• BIT for a 1-word field 

For example, suppose you want to determine whether the terminal device 
is set in the DEV field of a FAB, and suppose that the address of the 
FAB is in register R3 Then the proper macro is: 

$TESTBITS #FB$TRM,DEV,R3 ;Terminal device? 

As another example, suppose that you want to determine whether either 
the contiguous-area or the hard-location bit is set in the AOP field 
of an ALL block, and suppose that the address of the ALL block is in 
register R2. Then the proper macro is: 

$TESTBITS #XB$CTG!XB$HRD,A0P,R2 ;Contiguous or hard location? 



2.6 WRITING COMPLETION HANDLERS 

Recall that when you use an RMS-11 operation macro, you can specify 
the addresses of completion handlers for the operation; if you do so, 
the operation automatically calls the error handler (for a nonfatal 
error completion) or the success handler (for a success completion) 
when the operation completes, before control returns to your program. 

When execution control passes to your completion handler, it finds the 
following situation: 

• Register R5 contains the address of the argument block for the 
operation. 

If the operation is asynchronous, the address is the address 
of a copy of the original argument block for the operation. 

The second word of the argument block contains the address of 
the FAB or RAB for the operation. (Recall that the STS and 
STV fields of the FAB or RAB contain the completion code and 
completion value for the operation.) 
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If the operation was RENAME, the fifth word of the argument 
block contains the address of a second FAB for the operation. 

Other blocks are chained as they were when you used the 
operation macro that called the operation routine. 

A completion handler cannot determine from these values which RMS-11 
operation was executed, or what part of your program called the 
operation routine. You can, however, use the 1-word CTX field of the 
FAB or the 1-word CTX field of the RAB to indicate the context of the 
operation; RMS-11 does not disturb values in CTX fields. 

The completion handler must preserve the stack pointer (SP) , and must 
end with the RMS-11 completion-return macro in the format: 

$RETURN ;End of completion handler 



2.7 USING GET-SPACE ROUTINES 

Your program can provide and use get-space routines other than the one 
provided with RMS-11. It can set an initial get-space routine at 
assembly time, and it can change to other routines during program 
execution. Section 2.7.1 shows how to specify get-space routines, and 
how to obtain the address of the current get-space routine. Section 
2.7.2 shows how to write a get-space routine. 



2.7.1 Specifying Get-Space Routines 

To specify a get-space routine at assembly time, use the GSA$ macro in 
the format: 

GSA$ address ; Initialize get-space routine 

; address 

where address is the get-space routine entry address. If you specify 
as the address, or if you do not use the GSA$ macro, the initial 
get-space routine for the program is the RMS-11 routine. 

For example, to specify a routine that begins at the label MYSPAC, you 
would use: 

GSA$ MYSPAC 

To change the get-space routine during program execution, use the 
$SETGSA macro in the format: 

$SETGSA pointer ;Change get-space routine 

where pointer is the address of a location that contains the get-space 
routine entry address. If you specify the entry-point address as 0, 
the new get-space routine established is the RMS-11 routine. 

For example, to specify a routine that begins at the label NEWSPC, you 
could use: 

$SETGSA #NEWSPC 

Alternatively, if the location GSATMP contains the value NEWSPC, you 
could use: 

$SETGSA GSATMP 
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To obtain the address (in RO) of the current get-space routine during 
program execution, use the $GETGSA macro in the format: 

$GETGSA ;Get-space routine address into RO 

If the address returned in RO is 0, the current get-space routine is 
the RMS-11 routine. 



2.7.2 Writing a Get-Space Routine 

A get-space routine handles space in contiguous blocks. For a request 
for space, it allocates a contiguous block of space (or denies the 
request); for a release of space, it accepts a contiguous block of 
space. 

A get-space routine must have a proper interface to calling routines, 
and it should handle unallocated space properly. 



2.7.2.1 Get-Space Routine Interface - When RMS-11 calls a get-space 
routine, it either requests or releases a block of space. For a 
request for space, registers RO through R2 contain the following 
values : 

RO Address of pool free-space list (see next section) 
Rl Size (in bytes) of requested block 
R2 

If the get-space routine fills the request, it must clear the C bit 
and return the address of the first word of the allocated block in RO ; 
if it does not fill the request, it must set the C bit. In either 
case, the routine must preserve the stack and registers R3 through R6 . 

For a release of a block of space, registers RO through R2 contain the 
following values: 

RO Address of pool free-space list (see next section) 
Rl Size (in bytes) of released block 
R2 Address of first word being released 

For a release-space operation, the get-space routine returns no 
values; however, it must preserve the stack and registers R3 through 
R6. 



2.7.2.2 Pool Free-Space Lists - When RMS-11 calls your get-space 
routine, the address of a pool free-space list is in register RO . 
This free-space list specifies free space in one of the five pools 
described in Section 2.3; you can use this pool (which may or may not 
have adequate free space) , or you can use a pool of your own. 

The free-space list chains free contiguous blocks of the pool. The 
first word of each block contains the address of the next block; if 
the first word of a block is 0, it is the last block in the list. 

Blocks in the list are ordered by ascending virtual addresses; their 
addresses are word-aligned; their sizes are multiples of 4 bytes 
(allocations and deallocations must be rounded up to a multiple of 4, 
if necessary) . 
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The second word of each block contains the size (in bytes) of the 

block, including the 4-byte header; the first "block" in the list 

contains in its second word, since it is the header block for the 
list. 

Your get-space routine can use the specified pool list to get space 
for RMS-11; if it does this, it must properly maintain the list, and 
must (if possible) merge blocks back into the pool. 

The system routines $RQCB and $RLCB are suitable for handling pool 
free-space lists. These routines have interfaces that meet the 
requirements for your get-space routine; therefore your program can 
jump to $RQCB (for a space request) or $RLCB (for a space release) . 



2.8 ASSEMBLING THE PROGRAM 

When you assemble your program, you must cause the assembler to get 
RMS-11 macro and symbol definitions from a library, and you may have 
to correct errors indicated by messages from RMS-11 macros. 



2.8.1 Assembling with the RMSMAC Macro Library 

When you assemble your program, the assembler needs definitions for 
the RMS-11 macros and symbols that your program uses; these are in 
the RMS-11 macro library, RMSMAC. MLB. Include the following reference 
to the RMS-11 macro library in your assembler command string: 

LB : [ 1 , 1 ] RMSMAC . MLB/ML 



2.8.2 Assembly-Time Errors from RMS-11 Macros 

RMS-11 macros detect some errors during assembly. For each such 
error, a macro issues a .PRINT or .ERROR assembler directive with a 
message. Appendix B describes RMS-11 macro-generated messages and 
their meanings. 
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CHAPTER 3 
PROCESSING DIRECTORIES AND FILES 



This chapter discusses use of RMS-11 directory and file operations. 
The next sections discuss information and usage common to several 
directory and file operations: 

• Device characteristics 

• Logical channels 

• File specifications and identifiers 

• Private buffer pools 

• Completion status 

The sections after those provide an overview of the operations 
themselves (see Chapter 5 for detailed discussions): 

• Directory operations (except SEARCH) : ENTER, REMOVE, RENAME 
and PARSE 

• File operations: CREATE, OPEN, DISPLAY, ERASE, EXTEND, and 
CLOSE 

Finally, the last sections discuss: 

• SEARCH operation 

• Writing wildcard loops 



3.1 DEVICE CHARACTERISTICS 

A directory or file operation (except CLOSE, DISPLAY, or EXTEND) 
returns device characteristics. These characteristics are returned as 
masks in the 1-byte DEV field of the FAB. The device characteristics 
are: 

• Printer or terminal (indicated by the set FB$CCL mask in the 
1-byte DEV field of the FAB and the set FB$REC mask in the 
1-byte DEV field of the FAB; for a terminal, the FB$TRM mask 
in the 1-byte DEV field of the FAB is also set) ; RMS-11 
treats a printer or terminal as a unit-record device. 

Disk, DECtape, or DECTAPE II (indicated by the set FB$MDI mask 
in the 1-byte DEV field of the FAB); RMS-11 treats a disk, 
DECtape, or DECTAPE II as a disk device. 
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Unit-record device (indicated by the set FB$REC mask 
1-byte DEV field of the FAB) . 



in 



the 



Non-ANSI magtape or cassette tape (indicated by the set FB$SDI 
mask in the 1-byte DEV field of the FAB and the set FB$REC 
mask in the 1-byte DEV field of the FAB) ; RMS-11 treats a 
non-ANSI magtape or a cassette tape as a unit-record device. 



ANSI-format magtape (indicated by the set FB$SQD mask 
1-byte DEV field of the FAB) . 



in 



the 



3.2 LOGICAL CHANNELS 

An RMS-11 directory or file operation (except CLOSE, DISPLAY, or 
EXTEND) requires a logical channel; this channel is a path from the 
program to a specified device. 

When your program executes a CREATE or OPEN operation on the channel, 
the path is extended to the target file; until the file is closed, 
the channel is reserved for the specified FAB. 

Your program specifies the logical channel for a directory operation 
or for a CREATE, ERASE, or OPEN operation in the 1-byte LCH field of 
the FAB; the channel must not already be in use by the task. 

You can specify the initial device assignment for a logical channel in 
a Task Builder command file. The Task Builder also provides default 
initial device assignments for certain channels. Other logical 
channels are unassigned when your task begins executing. 

During task execution, channel assignments are made or changed by use 
of the ALUN$ system directive. For example, RMS-11 uses the ALUN$ 
directive to assign a logical channel for a directory operation or for 
a CREATE, ERASE, or OPEN operation; if the FAB and NAM block specify 
a device or device identifier, RMS-11 assigns the channel to that 
device; if the FAB and NAM block do not specify a device or device 
identifier, RMS-11 retains the device-channel assignment (if any), or 
assigns the channel to the device SY:. 



3.3 FILE SPECIFICATIONS AND IDENTIFIERS 

A file specification consists of the following elements (in the order 
given) : 



Device specification - the device where the file resides 

Directory specification - the directory on the device through 
which the file can be found 

File name - the name by which the file is known in the 
directory 

File type - the type by which the file is known in the 
directory 

File version - the version number by which the file is known 
in the directory 
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RMS-11 operations construct and use file specification strings and 
file identifiers to specify files. These strings and identifiers 
include: 

User-provided file specification strings 

• Expanded file specification strings 

• Resultant file specification strings 

• File, directory, and device identifiers 

This section discusses these strings and identifiers as they are used 
for nonwildcard operations; wildcard use is described in Section 3.8. 

For a CREATE, ENTER, ERASE, OPEN, PARSE, REMOVE, or RENAME operation, 
your program specifies two strings to be used in generating a full 
file specification: 

• A file specification string, called the file string (your 
program specifies the address of the file string in the 1-word 
FNA field of the FAB and the length of the string in the 
1-byte FNS field of the FAB) 

• A default file specification string, called the default string 
(your program specifies the address of the default string in 
the 1-word DNA field of the FAB and the length of the string 
in the 1-byte DNS field of the FAB) 

The operation routine uses these two strings to form an internal 
merged file specification string, called the merged string. The 
operation initially forms the merged string as follows: 

• It begins by taking available elements from the file string. 

• It then supplies missing elements from the default string (if 
they are available there) . The operation (when it completes) 
returns masks describing the results of this merge in the 
1-word FNB field of the NAM block (if you supplied a NAM block 
for the operation) . 

If elements are still missing from the merged string, the operation 
next adds the following elements: 

• Device - If the logical channel specified in the LCH field of 
the FAB is already assigned to a device, that device is used; 
otherwise the device SY: is used. 

• Directory - The task's current directory is used. 

• File name, type, and version - Nulls are used. 

If the operation is the PARSE operation, the merged string is 
complete. If you provided a NAM block, the PARSE operation returns 
the device identifier in the 2-word DVI field of the NAM block; if 
you provided an expanded string buffer, the PARSE operation returns 
the expanded string in the expanded string buffer (whose address is in 
the 1-word ESA field of the NAM block) . (Note that the device 
specification in an expanded string has usually been translated to the 
specification for a physical device.) 
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An operation other than PARSE continues by examining the FB$FID mask 
in the FOP field of the FAB. If the FB$FID mask is set, the operation 
adds the following elements: 

Device - If a device identifier is given in the NAM block, 
that device overrides the device in the merged string and the 
device specification is deleted from the merged string. 

• Directory - If a directory identifier is given in the NAM 
block, that directory overrides the directory in the merged 
string and the directory specification is deleted from the 
merged string. 

• File identifier - If a file identifier is given in the NAM 
block and if the operation is ERASE or OPEN, that file 
overrides the directory, file name, type, and version in the 
merged string and the specifications for those elements are 
deleted from the merged string. 

The merged string is then copied to the expanded string buffer (if you 
supplied one) as described for the PARSE operation above. The merged 
string plus applicable identifiers are called the fully qualified file 
specification, and define the file upon which the operation will be 
performed . 

The device, directory, and file identifiers for the file are returned 
in the NAM block (if you supplied one). These identifiers can be used 
as input to subsequent directory and file operations to speed 
processing by eliminating directory and file lookups. 

Note that a complete file specification is relevant only to a disk 
file. The directory specification is not relevant for ANSI magtape 
files; only the device specification is relevant for a file on a 
unit-record device. Irrelevant elements are not processed, and appear 
in the expanded string only if your program provides them in the file 
string or default string. 

NOTE: NULL, 0, OR -1 VERSION NUMBER 

If the version specification has not 
been deleted and is null, 0, or -1, it 
will later be replaced with the version 
number of the target file. 

A version number of -1 identifies the 
target file as the (otherwise) specified 
file with the lowest version number; a 
version number of -1 is illegal for a 
CREATE or ENTER operation, or for the 
new file specification for a RENAME 
operation. 

For an ERASE, OPEN, REMOVE, or RENAME 
(old specification) operation, a null or 
version number specifies the target 
file as the (otherwise) specified file 
with the highest version number. 

For a CREATE, ENTER, or RENAME (new 
specification) operation, a null or 
version number specifies that the 
operation is to create a new entry whose 
version number is one greater than the 
highest-numbered version of the 
(otherwise) specified file. 
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3.4 PRIVATE BUFFER POOLS 

Many RMS-11 operations require space from a buffer pool. A directory 
or file operation (except CLOSE, DISPLAY, or EXTEND) allows your 
program to specify a private buffer pool. Your program specifies the 
address of the pool in the 1-word BPA field of the FAB; it specifies 
the size (in bytes) of the pool in the 1-word BPS field of the FAB. 

The CLOSE operation returns (in the BPA and BPS fields) the address 
and size of the private buffer pool (if any) specified for the CREATE 
or OPEN operation that opened the file; until the file is closed, the 
pool is dedicated to the open file and must not be used for other 
purposes . 

If your program does not specify a private buffer pool, the operation 
uses the central buffer pool (which your program declares using 
pool-declaration macros) ; if your program specifies a private buffer 
pool, the operation uses that pool. 

The CLOSE, DISPLAY, and EXTEND operations, and all stream, record , and 
block operations use the pool specified by the CREATE or OPEN 
operation that opened the file. 



3.5 COMPLETION STATUS 

A directory or file operation returns a completion status code in the 
1-word STS field of the FAB, and a completion status value in the 
1-word STV field of the FAB. 



3.6 DIRECTORY OPERATIONS 

RMS-11 directory operations affect only directory entries (not the 
contents of files) . The directory operations are: 

• ENTER: create a directory entry 

• REMOVE: delete a directory entry 

• RENAME: replace a directory entry 

• PARSE: analyze a file specification 

• SEARCH: search directories 

The next sections provide an overview of the directory operations 
(except for the SEARCH operation, which is discussed in Section 3.8) . 



3.6.1 ENTER Operation 

A file specified as temporary when it was created has no directory 
entry; a file also has no directory entry if the entry has been 
deleted by the REMOVE operation. 

Your program can use the ENTER operation to create a directory entry 
for a file; this makes it possible for your program (and other 
programs) to specify the file to RMS-11 by its file specification. 

The ENTER operation uses the device and directory elements of the 
fully qualified file specification to determine the target directory; 
it then creates an entry in that directory using the file name, type, 
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and version elements of the fully qualified file specification, and 
the file identifier specified in the NAM block. 



3.6.2 REMOVE Operation 

Your program can delete the directory entry for a file by using the 
REMOVE operation; this does not affect either the existence of the 
file or the file contents, but only removes the path to the file. 

The device and directory elements of the fully qualified file 
specification specify the target directory; the file name, type, and 
version elements of the fully qualified file specification identify 
the entry to be removed from the directory. 



3.6.3 RENAME Operation 

Your program can replace the directory entry for a file by using the 
RENAME operation. The fully qualified file specification for the new 

directory entry must not specify a new device for the file, but 

otherwise it can specify elements different from the old file 
specification: directory, file name, file extension, and file version 
number . 

If you do not specify a device, the device associated with the old 
file specification is used. 

For both the old and new directory entries, the RENAME operation uses 

the device and directory elements of the fully qualified file 

specification to determine the target directory; it uses the file 

name, type, and version elements of the fully qualified file 
specification to identify the entry to be removed or created. 



3.6.4 PARSE Operation 

Your program can use the PARSE operation to analyze a file 

specification, or to prepare for a series of wildcard operations 

(described in Section 3.8). The results of the PARSE operation are 
described in detail in Section 3.3. 



3.7 FILE OPERATIONS 

RMS-11 file operations affect files as whole entities (but not 
individual records or blocks in files). The file operations are: 

• CREATE: create a file (and a corresponding directory entry) 
and open the file for processing 

• OPEN: open an existing file for processing 

• DISPLAY: write file information to control blocks 

ERASE: delete file contents (records or blocks) and remove 
directory entry 
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EXTEND: increase the allocation for a file 
CLOSE: close an open file 
The next sections discuss file operations. 

3.7.1 CREATE Operation 

The CREATE operation creates a new file and opens it for processing; 
unless the file is specified as a temporary file, the CREATE operation 
also creates a directory entry for the file. 

The CREATE operation uses the device and directory elements of the 
fully qualified file specification to determine the target directory; 
it then uses the file name, type, and version of the fully qualified 
file specification to form the entry in that directory. 

3.7.2 OPEN Operation 

Your program can establish an access path to a file by using the OPEN 
operation. This makes file information available to your program, and 
enables your program to use the following operations for the file: 

• DISPLAY operation (to make more file information available to 
your program) . 

• EXTEND operation (to allocate more space for the file) . 

• CONNECT operation (to establish a path to file records or 
blocks) . The CONNECT operation enables your program to use 
other stream operations and either record operations or block 
operations . 

• CLOSE operation (to release resources committed to the open 
file) . The CLOSE operation terminates the access path 
established by the CREATE or OPEN operation that opened the 
file. 



3.7.3 DISPLAY Operation 

If your program uses the OPEN operation to open a file, but does not 
provide control blocks and buffers for all the information that the 
OPEN operation can return, you may want to use the DISPLAY operation 
to obtain additional information while the file is open. 



3.7.4 ERASE Operation 

Your program can erase the contents of a file by using the ERASE 
operation, and (optionally) remove its directory entry. 

Unless your program provides a file identifier in the NAM block and 
sets the FB$FID mask in the 1-word FOP field of the FAB, the ERASE 
operation also removes the specified directory entry for the file. 



3-7 



PROCESSING DIRECTORIES AND FILES 

The ERASE operation uses the fully qualified file specification to 
determine the target file. If the operation removes the directory 
entry, it uses the device and directory elements of the fully 
qualified file specification to determine the target directory, and 
the file name, type, and version elements to determine the entry to be 
removed . 



3.7.5 EXTEND Operation 

Your program can increase the allocation for an open file by using the 
EXTEND operation. Note that RMS-11 automatically extends the file 
allocation when it needs more space; you can use the EXTEND operation 
to make large extensions (avoiding repeated automatic extensions) or 
exact extensions (avoiding wasteful automatic extensions). 



3.7.6 CLOSE Operation 

Your program can close an open file by using the CLOSE operation. 
This releases task and system resources (other than the file itself) 
and makes those resources available for other uses. 



3.8 WRITING WILDCARD LOOPS 

You can include wildcard characters in an RMS-11 file specification 
and use the PARSE and SEARCH operations to identify files that match 
the wildcard specification. This allows you to program a wildcard 
loop that successively (and selectively, if you wish) processes files 
matching the wildcard specification. 

An advantage of RMS-11 wildcarding over system wildcard commands is 
that your processing can be selective. For example, if you use a 
system wildcard command to rename a group of files, the entire group 
is renamed; if you use a wildcard loop in a program, the program can 
fully examine information about each file and even the contents of 
each file to decide whether to rename it. 

The next three sections show: 

• The structure of a wildcard loop and the behavior of directory 
and file operations in the loop 

• How to write a wildcard loop that nonselecti vely uses the 
ERASE, REMOVE, or RENAME operation on successive matching 

files 

• How to write a wildcard loop that selectively performs 
directory and file operations on successive matching files 



3.8.1 Introduction to Wildcarding 

This discussion assumes that you want to write a program loop that 

uses a wildcard input file specification, and that you want to use the 

same control blocks (FAB and NAM block) for all operations associated 
with the wildcard loop. 
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A series of wildcard operations can be viewed as having four steps: 

1. Initializing for wildcarding 

2. Finding the next matching file 

3. Operating on the found file 

4. Ending wildcarding 

The next sections discuss these steps. 



3.8.1.1 Initializing for Wildcarding - The PARSE operation 
initializes control blocks (FAB and NAM block) for wildcard 
operations. Place the $PARSE macro before the wildcard loop in your 
program. 

The PARSE operation sets the NB$WCH mask in the 1-word FNB field of 
the NAM block to show that wildcard operations are in progress. (Your 
program must clear the NB$WCH mask if it will not perform SEARCH 
operations after a PARSE operation.) 

The PARSE operation also forms a match-pattern in the expanded string 
buffer (whose address is in the 1-word ESA field of the NAM block) ; 
this match-pattern is used by subsequent wildcard SEARCH operations. 

A series of SEARCH operations requires a NAM block that specifies both 
expanded string and resultant string buffers. (The resultant string 
buffer is specified in the 1-word RSA field of the NAM block.) Your 
program must not alter the expanded string, the resultant string, or 
other NAM block contents between the PARSE operation and the end of 
the subsequent series of SEARCH operations. 



3.8.1.2 Finding the Next Matching File - The SEARCH operation finds 
the next file (if any) that matches the wildcard input file 
specification. (If the SEARCH operation cannot find another matching 
file, wildcarding ends; see Section 3.8.1.4.) 

The SEARCH operation returns a fully qualified file specification in 
the resultant string buffer, along with device, directory, and file 
identifiers for the found file. 

The SEARCH operation in your wildcard loop can either be explicit 
(your loop contains the $SEARCH macro) or, for some operations, 
implicit (RMS-11 automatically performs the SEARCH operation) . If you 
use the explicit SEARCH operation, place the $SEARCH macro inside the 
loop but before other operation macros. 

If you use an ERASE, REMOVE, or RENAME (old FAB) operation in the loop 
with the FB$FID mask in the 1-word FOP field of the FAB cleared, 
RMS-11 implicitly performs a SEARCH operation (to find the next 
matching file) before performing the ERASE, REMOVE, or RENAME 
operation. This allows your wildcard loop to omit the $SEARCH macro. 
(If the implicit SEARCH operation cannot find another matching file, 
wildcarding ends; see Section 3.8.1.4.) 
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3.8.1.3 Operating on the Found File - A number of directory and file 
operations are wildcard-transparent in the sense that they preserve 
both wildcard context information and information about the last-found 
file. This means that your program can use the operations within a 
wildcard loop without changing the wildcard context; the series of 
wildcard operations is continuable. 

The wildcard-transparent operations are CLOSE, DISPLAY, and EXTEND, 
and (if the FB$FID mask in the 1-word FOP field of the FAB is set) 
ERASE, OPEN, REMOVE, and RENAME (old FAB) . 



3.8.1.4 Ending Wildcarding - A series of wildcard operations (using a 
specific FAB and NAM block) ends when a directory or file operation 
discards wildcard context information or when your program clears the 
NB$WCH mask in the 1-word FNB field of the NAM block. 

Typically, the operation that ends wildcarding is a SEARCH operation 
that cannot find another matching file. It returns the ER$NMF 
completion status code and clears the NB$WCH mask in the 1-word FNB 
field of the NAM block. 

If your program exits from a wildcard loop before the SEARCH operation 
fails to find a matching file, the NB$WCH mask in the 1-word FNB field 
of the NAM block is still set, and your program must clear it. 

Executing the PARSE operation during a wildcard series ends that 
series and initializes control blocks for a new series. 

Executing a CREATE or ENTER operation, or an OPEN operation with the 
FB$FID mask in the 1-word FOP field of the FAB cleared, ends the 
wildcard series for that FAB. 



3.8.2 Nonselective ERASE, REMOVE, or RENAME Wildcard Operations 

You can write a wildcard loop "that performs nonselective ERASE, 
REMOVE, or RENAME operations on successive matching files, where 
RMS-11 implicitly performs a SEARCH operation before each ERASE, 
REMOVE, or RENAME operation. 

To do this, do the following: 

1. Use the PARSE operation to initialize control block fields 
for wildcarding. 

2. Clear the FB$FID mask in the 1-word FOP field of the FAB (for 
the RENAME operation, the old FAB) . This causes the ERASE, 
REMOVE, or RENAME operation to perform an implicit SEARCH 
operation before performing its own processing. 

3. Use the ERASE, REMOVE, or RENAME operation to operate on the 
next matching file. 

4. Examine the STS field of the FAB. If it contains the ER$NMF 
completion status code, there was not another matching file; 
in that case, go to step 7. 

5. Perform other in-loop processing (such as reporting the file 
specification of the erased, removed, or renamed file). 
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Go to step 2. 

The wildcard 
processing. 



series is finished; continue with other 



The following program segment illustrates this procedure, performing 
the ERASE operation. In the program segment, FABADR is a label giving 
the address of the FAB for the operations, and RO is used (for the 
$STORE and $COMPARE macros) to contain the address of the FAB. 



LOOP: 



DONE: 



$PARSE 

MOV 
$OFF 

$ERASE 

$COMPARE 

BEQ 

BR 



fFABADR 

#FABADR,R0 
#FB$FID,FOP,R0 

fFABADR 

#ER$NMF,STS,RO 

DONE 

LOOP 



;Set up for wildcarding 

;FAB address to RO 
;Use implicit search 

(FB$FID off) 
;Try to erase next file 
;Was there a matching file? 
;No more matching files 
;Other in-loop processing 
;0n to next matching file 

;Continue with other 
; processing 



3.8.3 Selective Wildcard Operations 

You can write a wildcard loop that performs directory and file 
operations on selected matching files, where your program explicitly 
performs a SEARCH operation at the beginning of each iteration of the 
loop. To do this, do the following: 

1. Use the PARSE operation to initialize control block fields 
for wildcarding. 

2. Use the ^SEARCH operation to obtain information about the next 
file that matches the wildcard specification. 

3. Examine the STS field of the FAB. If it contains the ER$NMF 
completion status code, there was not another matching file; 
in that case, go to step 6. 

4. Perform directory and file operations on the found file. If 
ERASE, OPEN, REMOVE, or RENAME operations are included, be 
sure the FB$FID mask in the 1-word FOP field of the FAB (for 
the RENAME operation, the old FAB) is set. 

Do not perform CREATE, ENTER, or PARSE operations, or OPEN 
operations with the FB$FID mask cleared; these operations 
end wildcarding. 

Do not perform ERASE, REMOVE, or RENAME operations with the 
FB$FID mask cleared; these operations perform an implicit 
SEARCH operation, advancing to the next matching file. 



5. Go to step 2. 

6. The wildcard series is finished; 
processing. 



continue with other 
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The following program segment illustrates the procedure, performing 
the ERASE operation on selected files. In the program segment, PABADR 
is a label giving the address of the FAB for the operations, and RO is 
used (for the $COMPARE macro) to contain the address of the FAB. 

$PARSE #FABADR ;Set up for wildcarding 

LOOP: $SEARCH #FABADR ;Find next matching file 

MOV #FABADR,R0 ;FAB address to RO 

$COMPARE #ER$NMF,STS,RO ;Any more matching files? 

BEQ DONE ;No more matching files 

. • • ;Decide whether to delete 

; file (if so, Z-bit on) 

BNE NOOP ;Don't delete file 

MOV #FABADR,R0 ;FAB address to RO 

$SET #FB$FID,FOP,RO ;Explicit SEARCH already done 

$ERASE #FABADR ;Erase file contents 

NOOP: . . . ;Other in-loop processing 

BR LOOP ;On to next matching file 

DONE: . . . ;Continue with other 

; processing 
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PROCESSING RECORDS AND BLOCKS 



This chapter describes use of RMS-11 stream, record, and block 
operations; its major sections are: 

• Synchronous and asynchronous operations 

• Completion status 

• Streams 

• Record processing 

• Block processing 

4.1 SYNCHRONODS AND ASYNCHRONOUS OPERATIONS 

An RMS-11 stream, record, or block operation executes either 
synchronously or asynchronously. 

4.1.1 Synchronous Operations 

If an operation executes synchronously, execution control is not 
returned to your program until the operation has completed; your 
program is idle during the operation's execution. To specify 
synchronous operation for a stream, record, or block operation, clear 
the RB$ASY mask in the 1-word ROP field of the RAB. 

4.1.2 Asynchronous Operations 

If an operation executes asynchronously, execution control may be 
returned to your program before the operation has completed; this 
allows your program to continue executing during the operation's 
execution. To specify asynchronous operation for a stream, record, or 
block operation, set the RB$ASY mask in the 1-word ROP field of the 
RAB. (You must also have specified the ASYN argument to the RAB$B 
macro when you declared the RAB, and must select the asynchronous 
support modules when you task build your program.) 

Your program can, for example, specify an asynchronous write operation 
and continue its processing even while the file processor is waiting 
for access to the device. 
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Only one operation (either synchronous or asynchronous) at a time may 
be active for a stream. Your program must make sure that an 
asynchronous operation has completed either by using the WAIT 
operation or by using completion routines to set user-defined flags. 

During processing, RMS-11 guards against illegal interleaving of 
operations on the same file as follows: 

• A file operation begins by verifying that no record operation 
is in progress for the target file. 

• A record operation begins by verifying that no file operation 
is in progress for the target file. 

• If a synchronous operation detects that it is executing within 
an asynchronous operation's completion handler, it verifies 
that no other record operation is in progress for the target 
file. 

If one of these verifications fails, the operation returns the ER$ACT 
completion in the STS field of the FAB or RAB. 

If your program attempts an operation using a FAB or RAB that is 
already in use by another operation, the attempted operation returns 
the fatal completion ER$ACT in RO (because the STS field of the FAB or 
RAB belongs to the other operation) . 

If your program attemps a WAIT operation within the completion handler 
for an asynchronous operation, the attempted operation returns the 
fatal completion ER$AST in RO (because otherwise a deadlock could 
occur) . 



4.2 COMPLETION STATUS 

A stream, record, or block operation returns a completion status code 
in the 1-word STS field of the RAB; it may also return a completion 
status value in the 1-word STV field of the RAB. 



4 . 3 STREAMS 

A stream is a path from your program to the data in a file. The 

CONNECT operation establishes a stream; for the CREATE or OPEN 

operation that opened the file, your program specified either record 
access or block access. 

If it specified record access, the stream is a record stream and 
supports only stream operations and record operations; if it 
specified block access, the stream is a block stream and supports only 
stream operations and block operations. 

For the CONNECT operation, your program specifies the FAB for the file 
(in the 1-word FAB field of the RAB), and the CONNECT operation 
returns an internal stream identifier (in the 1-word ISI field of the 
RAB) . All stream, block, and record operations (except CONNECT) 
identify the file using the internal stream identifier; the 
DISCONNECT operation terminates the stream, and clears the internal 
stream identifier. 



4-2 



PROCESSING RECORDS AND BLOCKS 

4.4 RECORD PROCESSING 

This section describes use of RMS-11 record processing. Its 
subsections are: 

Record streams: the paths from your program to file records 

• Record context: the "current location" of a stream in a file 

• Record access modes: the ways your program can access records 

• Record buffers: the locations of records in your program's 
space 

• Locate mode: a way of speeding record processing 

9 Stream operations: stream operations for a record stream 

• Record operations: operations that access records 

4.4.1 Record Streams 

A record stream is a path from your program to the records in a file. 
Your program establishes a record stream when it uses the CONNECT 
operation to connect a stream to a file (opened for record access by 
an earlier CREATE or OPEN operation) . A record stream supports stream 
operations and record operations, but not block operations. 

If the target file for a stream is a relative or indexed file, your 
program can establish more than one stream for the file; if, in 
addition, your program specifies access sharing, more than one task 
can establish streams for the file. 



4.4.2 Record Context 

A record stream has a record context, which consists of a 
current-record context and a next-record context. Some record 
operations use the current record or next record as the target for the 
operation; some stream and record operations change the 
current-record context, the next-record context, or both. 

The notion of "following record" is important to record context 
because the next-record context is often established as the record 
"following" the current record. The precise meaning of "following 
record" depends on the file organization: 

• In a sequential file, the record following a given record is 
the one immediately following it in physical sequence. 

• In a relative file, the record following a given record is the 
one in the first higher-numbered cell that contains a record. 

• In an indexed file, a record follows another only with respect 
to an index; each index imposes an order on the file records. 
The record following a given record (under a given index) is 
the record whose record key is the smallest in the file that 
is greater than the record key of the given record; among 
records having identical record keys, a record written later 
follows a record written earlier. 
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Note that although an operation may establish the next-record context, 
that context is not evaluated until another operation uses it. For 
example, if your program connects a stream to a relative file that 
contains records only in cells 5 and 10, a sequential access GET 
operation returns the record in cell 5 and establishes both 
current-record and next-record context; if another stream or task 
then inserts a record in cell 7 before your program executes a second 
sequential access GET operation, that GET operation returns the new 
record (cell 7) , even though the record did not exist when the 
next-record context was established. 



4.4.3 Record Access Modes 

The record operations FIND, GET, and PUT allow your program to specify 
a record access mode (in the 1-byte RAC field of the RAB) ; the record 
access mode determines the target record for the operation. The 
record access modes are: 

• Sequential access 

• Key access 

• RFA access 

The next sections discuss these access modes. 



4.4.3.1 Sequential Access - Your program specifies sequential access 
by setting the RB$SEQ code in the 1-byte RAC field of the RAB. A 
sequential access FIND or GET operation has as its target the next 
record. (Exception: a sequential access GET operation that 
immediately follows any FIND operation has as its target the current 
record, which is the record found by the FIND operation.) 

The target of a sequential access PUT operation depends on the file 
organization, as follows: 

• For a sequential file, a series of sequential access put 
operations must begin with the next-record context at the 
end-of-file. The series of PUT operations adds new records at 
the end-of-file. 

• For a relative file, a series of sequential access PUT 
operations must begin with the next-record context set such 
that the first cell examined is empty (unless the RB$UIF mask 
in the 1-word ROP field of the RAB is set) . The series of PUT 
operations adds new records in successive cells; if a 
nonempty cell is encountered, the PUT operation returns the 
ER$REX completion (unless the RB$UIF mask is set, in which 
case the existing record is overwritten) . 

• For an indexed file, a series of sequential access PUT 
operations does not depend on the next-record context; 
however, a PUT operation in the series returns the ER$SEQ 
completion if the value of the record primary key for the 
operation is less than the value of the record primary key for 
the preceding PUT operation. 

A sequential access FIND or GET operation sets the current-record 
context to the target record, and sets the next-record context to the 
record following the target record. Sequential access PUT operations 
leave both the current-record and next-record contexts undefined. 
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This targeting and context setting means, generally speaking, that a 
series of sequential access operations operates on successive records. 
Specifically, series of sequential access operations result as 
follows : 

A series of sequential access FIND operations sets the stream 
context to successive records. 

• A series of sequential access GET operations reads successive 
records. 

• A series of sequential access PUT operations writes successive 
records (for an indexed file, possibly interspersed with 
existing records) . 

• A series of paired sequential access FIND and sequential 
access GET operations reads successive records. 



4.4.3.2 Key Access - Your program specifies key access by setting the 
RB$KEY code in the 1-byte RAC field of the RAB. A key access FIND, 
GET, or PUT operation has as its target the record that your program 
specifies by specifying the key. For a relative file or for a 
sequential disk file with fixed-length records, your program specifies 
the key as a relative record number. Specify the relative record 
number in the 1-word KBF field of the RAB and the key size as or 4 
in the 1-byte KSZ field of the RAB. 

For a FIND or GET operation for an indexed file, your program 
specifies the index of reference and a key buffer that contains the 
record key. Specify the index of reference in the 1-byte KRF field of 
the RAB, the address of the key buffer in the 1-word KBF field of the 
RAB, and the key size in the 1-byte KSZ field of the RAB. 

A key access FIND or GET operation sets the current-record context to 
the record that is the target of the operation; a key access PUT 
operation leaves the current-record context undefined. 

A key access FIND or PUT operation does not affect the next-record 
context; a key access GET operation sets the next-record context to 
the record following the target record. 

The target of a key access FIND, GET, or PUT operation depends on the 
operation and on the file organization: 

• For a relative file or for a sequential disk file with 
fixed-length records, the key is a positive integer and 
specifies the position of the record in the file. This key is 
the relative record number (RRN) for the record; RRN 1 
specifies the first record, and so forth. 

If your program sets the RB$KGT mask in the 1-word ROP field 
of the RAB, a FIND or GET operation searches for a record 
whose RRN is greater than the given RRN; if it sets the 
RB$KGE mask in the 1-word ROP field of the RAB, the operation 
searches for a record whose RRN is greater than or equal to 
the given RRN; if it sets neither of these masks, the 
operation searches for a record with the given RRN. 
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Note that a FIND, GET, or PUT operation to a relative file or 
to a sequential disk file with fixed length records returns 
the RRN for the target record in the 2-word BKT field of the 
RAB. 

For a FIND or GET operation to an indexed file, the key 
specifies a record in the file whose record key matches the 
given key. Your program specifies both the key to be matched 
and the file index; the key data type must agree with the key 
data type for the index (string, packed decimal, binary, or 
signed integer) . 

For a string key, your program specifies the portion of the 
key that must be matched. If the value in the 1-byte KSZ 
field of the RAB is nonzero but is smaller than the record 
key, then only that smaller initial portion of the key must 
match . 

If your program sets the RB$KGT mask in the 1-word ROP field 
of the RAB, a FIND or GET operation searches for a record 
whose key is greater than the given key; if it sets the 
RB$KGE mask in the 1-word ROP field of the RAB, the operation 
searches for a record whose key is greater than or equal to 
the given key; if it sets neither of these masks, the 
operation searches for a record whose key exactly matches the 
given key. 

• For a PUT operation to an indexed file, the key (for each 

index) is in the record. The operation has no true target; 

the record is inserted at the proper place and each index is 
updated. 

This targeting and context setting means that although the target of 
the key access operation is a random (selected) record, the record 
context allows subsequent sequential access processing. Therefore 
your program can use key access to "jump" to a selected point in a 
file, then use sequential access to process successive records. 



4.4.3.3 RFA Access - Your program specifies RFA access by setting the 
RB$RFA code in the 1-byte RAC field of the RAB. An RFA access FIND or 
GET operation has as its target the record that your program specifies 
by RFA (record file address). (The FIND, GET, and PUT operations 
return the RFA for the target record; if your program saves the RFA, 
it can use RFA access for the record in subsequent FIND and GET 
operations.) Specify the RFA in the 3-word RFA field of the RAB. 

An RFA access FIND or GET operation sets the current-record context to 
the record that is the target of the operation. An RFA access FIND 
operation does not affect the next-record context; an RFA access GET 
operation set the next-record context to the record following the 
target record. 

This targeting and context setting means that although the target of 
the RFA access operation is a random (selected) record, the record 
context allows subsequent sequential access processing. Therefore 
your program can use RFA access to "jump" to a selected point in a 
file, then use sequential access to process successive records. 
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4.4.4 Record Buffers 

A PUT or UPDATE operation transfers a record from a record buffer (in 
your program's space) to a file; for a VFC record, the operation also 
transfers the fixed-length portion of the record from a separate 
record header buffer. Your program specifies the address of the 
record buffer in the 1-word RBF field of the RAB and the size of the 
record in the 1-word RSZ field of the RAB; for a VFC record, your 
program also specifies the address of the record header buffer in the 
1-word RHB field of the RAB. 

A GET operation transfers a record from a file to an RMS-11 internal 
I/O buffer and to a user buffer in your program's space. Your program 
specifies the address of the user buffer in the 1-word UBF field of 
the RAB and its size in the 1-word USZ field of the RAB. Along with 
the record, the GET operation returns the address of the record in the 
1-word RBF field of the RAB and its size in the 1-word RSZ field of 
the RAB. 

For a VFC record, a GET operation also transfers the fixed-length 
portion of the record to a separate record header buffer in your 
program's space. Your program specifies the address of the record 
header buffer in the 1-word RHB field of the RAB. 

Exception: if your program specifies locate mode for a GET operation, 
RMS-11 may not transfer the record to the user buffer; see the next 
section for a discussion of locate mode. 



4.4.5 Locate Mode 

The GET and PUT operations normally use RMS-11 internal I/O buffers as 
intermediate storage between your program's buffers (record or user 
buffers) and the file. By specifying locate mode for a GET or PUT 
operation, your program requests RMS-11 to transfer records only 
between its I/O buffers and the file, thus saving time. Your program 
specifies locate mode by setting the RB$LOC mask in the 1-word ROP 
field of the RAB. 

If your program specifies locate mode for a GET operation, RMS-11 may 
transfer the record only to its internal I/O buffer (but not to the 
user buffer) . The GET operation routine decides whether to honor the 
locate-mode request or to transfer the record to the user buffer 
anyway; the operation returns the address and size of the retrieved 
record (informing your program of the record's location — the user 
buffer or the I/O buffer) . 

If your program specifies locate mode for a PUT operation, RMS-11 
recognizes that the record may already be in its I/O buffer and if so 
transfers it to the file from there. 

Your program has (in the 1-word RBF field of the RAB) the address of a 
location (in the I/O buffer if possible, otherwise in the user buffer) 
that is suitable for building the next record; this address is 
returned either by a previous locate-mode PUT operation or by an 
initial locate-mode CONNECT operation. Therefore, if you use the 
CONNECT operation for a stream that will use locate-mode PUT 
operations, your program must specify locate mode for the CONNECT 
operation, and must specify a user buffer (the address in the 1-word 
UBF field of the RAB and the size in the 1-word USZ field of the RAB) . 

Note that specifying locate mode for a PUT operation has no effect 
unless the file is sequential, the access mode is sequential, and the 
record format is other than stream record format. 
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4.4.6 Stream Operations 

Stream operations affect stream context and I/O buffers (but not file 
records) . The stream operations for a record stream are: 

CONNECT: establish a record stream 

• PLUSH: write unwritten buffers for a stream 

• FREE: free locked bucket for a stream 

• NXTVOL: set stream context to beginning of next volume 

• REWIND: set stream context to beginning of current file 

• WAIT: wait for completion of asynchronous operation 

• DISCONNECT: terminate a record stream 
The next sections discuss these operations. 



4.4.6.1 CONNECT Operation - Your program uses the CONNECT operation 
to establish a record stream. (The stream is a record stream because 
your program specified record access for the CREATE or OPEN operation 
for the file.) 

The current-record context after a CONNECT operation is undefined; 
the next-record context is (by default) the first record in the file. 

For an indexed file, your program must specify an initial index of 
reference so that the record context is initialized properly. 

For a sequential file, your program can specify that the initial 
record context is to be at the end-of-file (instead of the beginning 
of the file); in that case, the next-record context after the 
operation is the end-of-file. 

For a sequential disk file, your program specifies the number of 
blocks in the I/O buffer for the stream; for a relative or indexed 
file, your program specifies the number of I/O buffers for the stream. 

If the stream will use locate-mode PUT operations, your program must 
also specify locate mode and supply a user buffer. The CONNECT 
operation returns the address of a location suitable for building the 
first record to be output; see Section 4.4.5. 



4.4.6.2 FLUSH Operation - Your program can use the FLUSH operation to 
write any unwritten buffers for a stream (for example, to increase 
data integrity by ensuring that all changes have been written to the 
file) ; the FLUSH operation does not affect record context, except 
that the current-record context is undefined for a following TRUNCATE 
or UPDATE operation to a sequential file. 

Note one special case: if the file was opened for deferred writing, 
but not for write sharing, then the buffer may be controlled by 
another record stream and will not be written by the FLUSH operation. 
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4.4.6.3 FREE Operation - Your program can use the FREE operation to 
free a locked bucket for a stream; the FREE operation does not affect 
stream context, except that the current-record context is undefined 
for a following DELETE, TRUNCATE, or UPDATE operation. 



4.4.6.4 NXTVOL Operation - Your program can use the NXTVOL operation 
to advance the context for a stream to the beginning of the next 
magtape volume. The current-record context after the operation is 
undefined; the next-record context is the first record of the new 
volume. 



4.4.6.5 REWIND Operation - Your program can use the REWIND operation 

to reset the context for a stream to the beginning-of-f ile or, for a 

multivolume magtape file, the beginning-of-volume (if it is not the 
first volume of the file) . 

The current-record context after the operation is undefined; the 

next-record context is the first record in the volume (for a 

multivolume magtape file) or the file; for an indexed file, your 

program specifies the index of reference for the operation so that the 
stream context is initialized properly. 



4.4.6.6 WAIT Operation - When your program uses asynchronous 
operation for a stream, it must eventually use the WAIT operation to 
suspend processing until the asynchronous operation has completed; 
the WAIT operation does not affect stream context. 



4.4.6.7 DISCONNECT Operation - Your program can use the DISCONNECT 
operation to terminate a record stream, thus recovering the resources 
committed for the stream (primarily pool space) . The DISCONNECT 
operation also discards record context and the internal stream 
identifier . 



4.4.7 Record Operations 

Record operations affect stream context, buffers (I/O, user, and 
record), and file records. The record operations are: 

• FIND: transfer a record from a file to an I/O buffer 

• GET: transfer a record from a file to an I/O buffer and to a 
user buffer 

• PUT: transfer a record from a user buffer to a file 

• DELETE: remove a record from a file 

• UPDATE: replace a record in a file 

TRUNCATE: remove the current record and all following records 
from a sequential file 

The next sections discuss these operations. 
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4.4.7.1 FIND Operation - Your program can use the FIND operation to 
transfer a record (or part of a record) from a file to an I/O buffer; 
the FIND operation does not transfer the record to a user buffer. 

Your program specifies an access mode (sequential, key, or RFA) for 
the FIND operation; Section 4.4.3 describes the target record and 
context-setting for the FIND operation (Section 4.4.3.1 for sequential 
access, 4.4.3.2 for key access, and 4.4.3.3 for RFA access). 

For a relative file or for a sequential disk file with fixed-length 
records, the FIND operation returns the relative record number (RRN) 
and the record file address (RFA) for the found record; for other 
files, the FIND operation returns only the RFA for the found record. 



4.4.7.2 GET Operation - Your program can use the GET operation to 
transfer a record from a file to an I/O buffer and to a user buffer 
(which your program specifies) . 

Your program specifies an access mode (sequential, key, or RFA) for 
the GET operation; Section 4.4.3 describes the target record and 
context-setting for the GET operation (Section 4.4.3.1 for sequential 
access, 4.4.3.2 for key access, and 4.4.3.3 for RFA access). 

The GET operation returns the address and size of the retrieved 

record, along with its RFA; for a relative file or for a sequential 

disk file with fixed-length records, the GET operation also returns 
the RRN for the retrieved record. 



If your program specifies locate mode for the GET operation, it 
also specify a user buffer; see Section 4.4.5. 



must 



4.4.7.3 PUT Operation - Your program can use the PUT operation to 
transfer a record from a user buffer to an I/O buffer and to a file. 

Your program specifies an access mode (sequential or key) for the PUT 
operation; Section 4.4.3 describes the target record and 
context-setting for the PUT operation (Section 4.4.3.1 for sequential 
access, 4.4.3.2 for key access). 

Your program can specify that RMS-11 must honor bucket fill numbers. 

For an indexed file, your program can specify that each PUT operation 

in a series is part of a mass insertion; for a relative file, your 

program can specify that the PUT operation should overwrite the target 
record (if any) . 

The PUT operation returns the RFA for the inserted record; for a 
relative file or for a sequential disk file with fixed-lentgh records, 
the PUT operation also returns the RRN for the inserted record. 

If your program specifies locate mode for the PUT operation, it must 
also specify a user buffer. The PUT operation returns the address of 
a location suitable for building the next output record; see Section 
4.4.5. 
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4.4.7.4 DELETE Operation - Your program can use the DELETE operation 
to remove a record from a relative or indexed file. The target of a 
DELETE operation is the current record. 

The current-record context after a DELETE operation is undefined; the 
next-record context is unchanged. 

For an indexed file, your program can specify that RMS-11 must use the 
fast-deletion procedure. However, this procedure is faster because it 
deletes only those alternate index pointers that it must; future 
retrieval operations may be slowed by the presence of undeleted 
alternate index pointers. 



4.4.7.5 UPDATE Operation - Your program can use the UPDATE operation 
to transfer a record from a user buffer to a file (overwriting the 
existing record) . The target of the UPDATE operation is the current 
record, which is overwritten. 

The current-record context after an UPDATE operation is undefined; 
the next-record context is unchanged. 

Your program specifies the record buffer for the record to be inserted 
(and, for a VFC record, the VFC-header buffer). 



4.4.7.6 TRUNCATE Operation - Your program can use the TRUNCATE 
operation to remove the current record and all following records 
(through the end-of-file) from a sequential file. The current-record 
context after a TRUNCATE operation is undefined; the next-record 
context is the new end-of-file. 



4.5 BLOCK PROCESSING 

This section describes use of RMS-11 block processing. Its 
subsections are: 

• Block streams: the paths from your program to file blocks 

• Block context: the "current location" of a stream in a file 

• Block access modes: the ways your program can access blocks 

• Block buffers: the locations of blocks in your program's 
space 

• Stream operations: stream operations for a block stream 

• Block operations: operations that access blocks 



4.5.1 Block Streams 

A block stream is a path from your program to the blocks in a file. 
Your program establishes a block stream when it uses the CONNECT 
operation to connect a stream to a file (opened for block access by an 
earlier CREATE or OPEN operation) . A block stream supports stream 
operations and block operations, but not record operations. 
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4.5.2 Block Context 

A block stream has a block context, which consists of a readable-block 
context and a writable-block context. The READ operation uses the 
readable-block as its target block; the WRITE operation uses the 
writable-block as its target block; block operations change both the 
readable-block and the writable-block contexts. 

For a disk file, your program can use the READ or WRITE operation to 
read or write multiple blocks in a single operation. In that case, 
reading or writing begins at the readable block or the writable block 
(respectively), and continues through the number of blocks requested. 



4.5.3 Block Access Modes 

The block operations READ and WRITE allow your program to specify a 

block access mode (in the 2-word BKT field of the RAB) ; the block 

access mode determines the target block for the operation. The block 
access modes are: 

• Sequential access 

• VBN access 

For a magtape file, your program can use either sequential block 
access or VBN access; however, the program must access one block at a 
time, and in sequential order (unless it uses the SPACE operation to 
position the magtape) . 

The next sections discuss these access modes. 



4.5.3.1 Sequential Access - Your program specifies sequential block 
access by giving the value in the 2-word BKT field of the RAB. A 
sequential access READ operation has as its target the readable block; 
it sets the readable-block context to the next-following unread block, 
and sets the writable-block context to the target block (first block 
read for that READ operation) . 

A sequential access WRITE operation has as its target the writable 
block; it sets both the readable-block and writable-block contexts to 
the next-following unwritten block. 

This targeting and context setting has the following results: 

• A series of sequential access READ operations reads successive 
blocks. 

• A series of sequential access WRITE operations writes 
successive blocks. 

• A series of paired READ and WRITE operations updates 
successive blocks. 
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4.5.3.2 VBN Access - A VBN access READ or WRITE operation reads or 
writes blocks beginning with a virtual block that your program 
specifies. Specify the virtual block number in the 2-word BKT field 
of the RAB. 

Note that your program can use VBN access to move to a random position 
in a disk file, and then use sequential block access to process blocks 
sequentially from that point. 



4.5.4 Block Buffers 

Your program specifies a user buffer for the READ operation; the 
operation returns the address of the first-read byte and the number of 
bytes read. Specify the address of the user buffer in the 1-word UBF 
field of the RAB and its size in the 1-word USZ field of the RAB; the 
READ operation returns the address of the first-read byte in the 
1-word RBF field of the RAB and the number of bytes read in the 1-word 
RSZ field of the RAB. 

Your program specifies the buffer containing the writable data for the 
WRITE operation. Specify the buffer address in the 1-word RBF field 
of the RAB and its size in the 1-word RSZ field of the RAB. 



4.5.5 Stream Operations 

Stream operations affect stream context and I/O buffers (but not file 
blocks) . The stream operations for a block stream are: 

• CONNECT: establish a block stream 

• FREE: free a locked block for a stream 

• WAIT: wait for completion of asynchronous operation 

• DISCONNECT: terminate a block stream 
The next sections discuss these operations 



4.5.5.1 CONNECT Operation - Your program uses the CONNECT operation 
to establish a block stream. (The stream is a block stream because 
your program specified block access for the CREATE or OPEN operation 
for the file.) 

After a CONNECT operation, both the readable-block and writable-block 
contexts are the first block in the file. 



4.5.5.2 FREE Operation - Your program can use the FREE operation to 
free a locked block for a stream; the FREE operation does not affect 
stream context. 
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4.5.5.3 WAIT Operation - When your program uses asynchronous 
operation for a stream, it must eventually use the WAIT operation to 
suspend processing until the asynchronous operation has completed; 
the WAIT operation does not affect stream context. 



4.5.5.4 DISCONNECT Operation - Your program can use the DISCONNECT 
operation to terminate a block stream, thus recovering the resources 
committed for the stream. The DISCONNECT operation also discards 
block context and the internal stream identifier. 



4.5.6 Block Operations 

Block operations affect stream context, block buffers, and file 
blocks. The block operations are: 

• READ: transfer blocks from a file to a block buffer 

• WRITE: transfer blocks from a block buffer to a file 

• SPACE: set block context for a magtape file 
The next sections discuss these operations. 



4.5.6.1 READ Operation - Your program can use the READ operation to 
transfer blocks from a file to a block buffer. Your program specifies 
an access mode (sequential or VBN) for the READ operation; Section 
4.5.3.1 describes sequential access; Section 4.5.3.2 describes VBN 
access . 



4.5.6.2 WRITE Operation - Your program can use the WRITE operation to 
transfer blocks from a block buffer to a file. Your program specifies 
an access mode (sequential or VBN) for the WRITE operation; Section 
4.5.3.1 describes sequential access; Section 4.5.3.2 describes VBN 
access. 

Note that because the WRITE operation always writes to the file 
immediately, the FLUSH operation has no use for block access. 



4.5.6.3 SPACE Operation - Your program can use the SPACE operation to 
set block context for a magtape file; the context is moved forward or 
backward the specified number of blocks. After a SPACE operation, 
both the readable-block and writable-block contexts are the specified 
block . 
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CHAPTER 5 
OPERATION MACRO DESCRIPTIONS 



This chapter describes RMS-11 operation macros and the operation 
routines they call. Each section of the chapter describes an 
operation macro and its corresponding operation. (For the $FIND, 
$GET, $PUT, $READ, and $WRITE macros, there is a separate description 
for each access method.) 

Each description is divided into the following parts: 

• FORMAT - the format for the macro and its parameters 

• CONTROL BLOCKS - the required and optional control blocks for 
the operation 

• OPTIONS - the options that you can select for the operation, 
and the control block fields and values that control the 
options 

• STREAM CONTEXT - the current-record and next-record contexts 
(for a record stream) or the readable-block and writable-block 
contexts (for a block stream) after the operation completes 

• RETURNED VALUES - the values that the operation routine 
returns in control block fields and buffers 

• CHECKLISTS - a list of the control block fields that you 
supply to specify options, and a list of the control block 
fields that contain returned values 

The operation macros are: 

• $CLOSE - Close an open file 

• $CONNECT - Connect a record stream to an open file 

• $CREATE - Create a new file and open it for processing 

• $DELETE - Remove a record from a file 

• $DISCONNECT - Disconnect a record stream 

• $DISPLAY - Write file data into control block fields 

• $ENTER - Enter a file specification into a directory 

• $ERASE - Erase an existing file 

$EXTEND - Extend the allocation for an open file 
$FIND - Set the stream context to a record in a file 
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$FLUSH - Write any unwritten buffers for a stream 
$FREE - Unlock a bucket locked by a stream 
$GET - Retrieve a record from a file 

• $NXTVOL - Set stream context to the beginning of the next 
magtape volume 

• $OPEN - Open an existing file 

• $PARSE - Write file data into a NAM block 

• $PUT - Insert a record into a file 

• $READ - Read blocks from a file 

• $REMOVE - Delete a file specification from a directory 

• $RENAME - Rename an existing file 

• $REWIND - Set stream context to beginning-of-f ile 

• $SEARCH - Search directories for a file specification 

• $SPACE - Move magtape block stream context forward or backward 

• $TRUNCATE - Remove all following records from a file 

• $UPDATE - Replace a record in a file 

• $WAIT - Wait for asynchronous completion for stream 

• $WRITE - Write blocks into a file 
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5.1 $CLOSE MACRO 

The $CLOSE macro calls the CLOSE operation routine to close an open 
file . 



FORMAT 

The format for the $CLOSE is: 

$CLOSE f abaddr [ , [erraddr] [ ,sucaddr] ] 

where f abaddr is the address of the FAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 

CONTROL BLOCKS 

You must supply a FAB for the CLOSE operation. 

If you supply a PRO block, the CLOSE operation reads its fields to 
obtain new owner and protection codes for the file. 

To supply XABs (ALL, DAT, KEY, PRO, and SUM blocks) for the CLOSE 
operation, specify the address of the first XAB in the 1-word XAB 
field of the FAB; specify the address of the next XAB (if any) in the 
1-word NXT field of each XAB; specify in the NXT field of the last 
XAB. 

All KEY blocks must be together in the chain of XABs, and must be in 
ascending order (by the index reference number in the 1-byte REF field 
of the KEY block) ; the index reference numbers need not be 
consecutive. 

All ALL blocks must be together in the chain of XABs, and must be in 
ascending order (by the area identifier in the 1-byte AID field of the 
ALL block); the area identifiers need not be consecutive. 

Multiple DAT, PRO, or SUM XABs are illegal. 
OPTIONS 

Internal File Identifier 

The CLOSE operation reads the internal file identifier for the file 
from the 1-word IFI field of the FAB. This identifier was written by 
the CREATE or OPEN operation when the file was opened. 

File Owner and Protection 

If you want to change the owner of the target file, specify the 
project (or group) portion of the owner code in the 1-word PRJ field 
of the PRO block, and specify the programmer (or member) portion in 
the 1-word PRG field of the PRO block; if you specify for both 
these fields, the PRO block (including the PRO field) is ignored. 

If you want to change the file protection for the target file, specify 
the protection code in the 1-word PRO field of the PRO block (and 
specify a nonzero value in the PRG or PRJ field); if you specify in 
this field, the operating system uses its defaults. 
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Rewinding Magtape 



For a magtape file, if you want the magtape rewound when the file is 
closed, set the FB$RWC mask in the 1-word FOP field of the FAB. Note 
that if the FB$RWC mask was set when the file was opened (by the 
CREATE or OPEN operation) , setting the mask has no effect for the 
CLOSE operation. 

STREAM CONTEXT 

The CLOSE operation destroys stream context for any streams connected 
by the closing file (after writing any unwritten buffers for those 
streams) . 

RETURNED VALUES 



Private Buffer Pool 

The CLOSE operation writes the address of the private buffer pool (if 
any) for the file in the 1-word BPA field of the FAB; if the CLOSE 
operation clears the BPA field, the file had no private buffer pool. 

If the file had a private buffer pool, the CLOSE operation writes the 
size (in bytes) of the pool in the 1-word BPS field of the FAB, or 
clears this field if the file did not use a private buffer pool. 

Internal File Identifier 

The CLOSE operation clears the 1-word IFI field of the FAB. 

Completion Status and Value 

The CLOSE operation returns completion status in the 1-word STS field 
of the FAB and returns a completion value in the 1-word STV field of 
the FAB. Appendix A lists completion status symbols and values. 

CHECKLISTS 

Table 5-1 lists control block fields that are input to the CLOSE 
operation. Table 5-2 lists control block fields that are output by 
the CLOSE operation. 
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Table 5-1: CLOSE Input Fields 



Block Field Description 



ALL 


AID 


ALL 


NXT 


DAT 


NXT 


FAB 


FOP 



FAB 


IFI 


FAB 


XAB 


KEY 


REF 


KEY 


NXT 


PRO 


NXT 


PRO 


PRG 


PRO 


PRJ 


PRO 


PRO 


SUM 


NXT 



Area number 

Next XAB address 

Next XAB address 

File processing option mask 

FB$RWC Rewind magtape after closing file 

Internal file identifier 

XAB address 

Index reference number 

Next XAB address 

Next XAB address 

Programmer or member portion of file owner code 

Project or group portion of file owner code 

File protection code 

Next XAB address 



Table 5-2: CLOSE Output Fields 



Block Field Description 



FAB 


BPA 


FAB 


BPS 


FAB 


IFI 


FAB 


STS 


FAB 


STV 



Private buffer pool address 
Private buffer pool size (bytes) 
Internal file identifier 
Completion status code 
Completion status value 
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5.2 $CONNECT MACRO 

The $CONNECT macro calls the CONNECT operation routine to connect a 
record stream to an open file, and initialize the stream context. 

FORMAT 

The format for the $CONNECT is: 

$CONNECT rabaddr [ , [erraddr] [ ,sucaddr] ] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 

CONTROL BLOCKS 

You must supply a RAB for the CONNECT operation. 
You must supply a FAB for the CONNECT operation. 

OPTIONS 

File Identification 

Specify the address of the FAB in the 1-word FAB field of the RAB. 
The CONNECT operation reads the internal file identifier for the file 
from the 1-word IFI field of the FAB. 

I/O Buffers 

For a sequential disk file, specify the size (in blocks) of the RMS-11 
I/O buffer for the stream in the 1-byte MBC field of the RAB; the 
largest legal value is 63. If you specify 0, the CONNECT operation 
uses a buffer of one block. For a relative file, an indexed file, or 
a sequential nondisk file, the CONNECT operation ignores the MBC 
field. 

For a relative or indexed file, specify the number of I/O buffers for 
the stream in the 1-byte MBF field of the RAB. For a sequential file, 
specify in the MBF field. If you specify 0, the CONNECT operation 
uses the minimum number of buffers: one for a sequential or relative 
file, or two for an indexed file. 

User Buffer (Locate Mode for Sequential File) 

If you are connecting to a sequential file, and if you intend to 
execute PUT operations in locate mode for the connected stream, then: 

• Specify the address of the user buffer in the 1-word UBF field 
of the RAB. 

Specify the size (in bytes) of the user buffer in the 1-word 
USZ field of the RAB. 

Set the RB$LOC mask in the 1-word ROP field of the RAB. 
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This assures proper handling of the first PUT operation for the 
stream. 

Key of Reference (Indexed File) 

For an indexed file, specify the key of reference in the 1-byte KRF 
field of the RAB. This value specifies the index to be used in 
establishing initial record context: for the primary index, 1 for 
the first alternate index, and so forth. 

Initial Stream Context (Sequential File) 

If you want to initialize the next-record context of a sequential file 
to the end-of-file, set the RB$EOF mask in the 1-word ROP field of the 
RAB; if you do not set this mask, the CONNECT operation initializes 
the next-record context to the first record in the file (or to the 
end-of-file if the file is empty) . 

Asynchronous Operation 

If you want to execute the CONNECT operation asynchronously, set the 
RB$ASY mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the CONNECT operation executes synchronously. (Your 
program must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 

STREAM CONTEXT 

For a record-access file, the current-record context after a CONNECT 
operation is undefined; the next-record context is the first record 
in the file (under the specified index for an indexed file) , or the 
end-of-file, if the file is empty. 

For a block-access file, both the readable-block and writable-block 
contexts after a CONNECT operation are the first block in the file. 

RETURNED VALUES 

Internal Stream Identifier 

The CONNECT operation writes an internal stream identifier in the 
1-word ISI field of the RAB. Do not destroy this identifier; all 
other stream, record, and block operation routines read it. 

Record Buffer 

The CONNECT operation copies the value from the UBF field into the 
1-word RBF field of the RAB (the record address); this prepares the 
record buffer for your use in case the first record operation for the 
stream is a locate-mode PUT operation to a sequential file. 

RFA 

For block access, the CONNECT operation returns the logical 
end-of-file value in the 3-word RFA field of the RAB. The first two 
words of this field are the VBN in which the logical end-of-file 
occurs, and the third word is the offset of the first byte beyond the 
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logical end-of-file within that block. 
is meaningful only for disk files. 



This logical end-of-file value 



Completion Status and Value 

The CONNECT operation returns completion status in the 1-word STS 
field of the RAB and returns a completion value in the 1-word STV 
field of the RAB. Appendix A lists completion status symbols and 
values . 



CHECKLISTS 

Table 5-3 lists control block fields that are input to the CONNECT 
operation. Table 5-4 lists control block fields that are output by 
the CONNECT operation. 



Table 5-3: CONNECT Input Fields 



Block Field Description 



FAB 


IFI 


RAB 


FAB 


RAB 


KRF 


RAB 


MBC 


RAB 


MBF 


RAB 


ROP 



RAB UBF 
RAB USZ 



Internal file identifier 

FAB address 

Key of reference 

Multiblock count 

Multibuffer count 

Record processing option mask 

RB$ASY Asynchronous operation 
RB$EOF Position to end-of-file 
RB$LOC Locate mode 

User buffer address 
User buffer size (bytes) 



Table 5-4: CONNECT Output Fields 



Block Field Description 



RAB 


ISI 


RAB 


RBF 


RAB 


RFA 


RAB 


STS 


RAB 


STV 



Internal stream identifier 
Record buffer address 
End-of-file address 
Completion status code 
Completion status value 
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5.3 $CREATE MACRO 

The $CREATE macro calls the CREATE operation routine to create a new 
file and open it for processing. 

FORMAT 

The format for the $CREATE is: 

$CREATE fabaddr [, [erraddr] [,sucaddr] ] 

where fabaddr is the address of the FAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 

CONTROL BLOCKS 

You must supply a FAB for the CREATE operation. 

If you supply a NAM block, the CREATE operation reads its fields to 
obtain the expanded string buffer, and writes identifiers in its 
fields. 

To supply a NAM block for the CREATE operation, specify the address of 
the NAM block in the 1-word NAM field of the FAB. 

Each ALL block that you supply defines one area in the created file, 
and you can place the area at a specific location. If you supply no 
ALL blocks, the file has one area; you define this area in the FAB, 
but you cannot place the area at a specific location. You cannot 
supply more than one ALL block for a sequential or relative file. 

Each KEY block that you supply defines one index for the created file. 
You must supply at least one KEY block for an indexed file; you 
cannot supply KEY blocks for a relative or sequential file. 

If you supply a PRO block, the CREATE operation reads its fields to 
obtain the protection for the file. 

To supply XABs (ALL, DAT, KEY, PRO, and SUM blocks) for the CREATE 
operation, specify the address of the first XAB in the 1-word XAB 
field of the FAB; specify the address of the next XAB (if any) in the 
1-word NXT field of each XAB; specify in the NXT field of the last 
XAB. 

All KEY blocks must be together in the chain of XABs, and must be in 

ascending order (by the index reference number in the 1-byte REF field 

of the KEY block) ; the index reference numbers must be consecutive 
beginning with 0. 

All ALL blocks must be together in the chain of XABs, and must be in 

ascending order (by the area identifier in the 1-byte AID field of the 

ALL block) ; the area identifiers must be consecutive beginning with 
0. 

Multiple DAT, PRO, or SUM XABs are illegal. 

Note that if the LAN field of a KEY XAB is 0, RMS-11 will use the area 
specified in the IAN field for the lowest level index for that index. 
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OPTIONS 



File Specification 



The CREATE operation constructs the full file specification from the 
file string, the default string (which contributes only elements not 
present in the file string) , and RMS-11 defaults (which contribute 
elements not present in either the file string or the default string) . 



RMS-11 defaults are 



Device — The device to which the specified logical channel is 
assigned, or SY: if the specified logical channel is not 
assigned to any device. 

• Directory — The current directory for the task. 

• Name, type, version — Defaulted to null. 

The file string and the default string must not contain wildcards. 

Specify the address of the file string in the 1-word FNA field of the 

FAB. Specify the size (in bytes) of the file string in the 1-byte FNS 

field of the FAB; if you specify in the FNS field, the CREATE 
operation uses no file string. 

Specify the address of the default string in the 1-word DNA field of 

the FAB. Specify the size (in bytes) of the default string in the 

1-byte DNS field of the FAB; if you specify in the DNS field, the 
CREATE operation uses no default string. 

If you set the FB$FID mask in the 1-word FOP field of the FAB and 
supply a NAM block, the CREATE operation reads the device identifier 
from the 2-word DVI field of the NAM block; if this value is nonzero, 
the specified device overrides the device in the merged string. 

In the same circumstance, the CREATE operation reads the directory 
identifier from the 3-word DID field of the NAM block; if this value 
is nonzero, the specified directory overrides the directory in the 
merged string. 

Expanded String Buffer 

If you want the CREATE operation to return the expanded string for the 
created file, provide a buffer for the string. Specify the address of 
the expanded string buffer in the 1-word ESA field of the NAM block 
and its size (in bytes) in the 1-byte ESS field of the NAM block; if 
you specify in the ESS field, the CREATE operation does not return 
the expanded string. 

Supersession of Existing File 

If you want to create a file that supersedes an existing file with the 
same specification, set the FB$SUP mask in the 1-word FOP field of the 
FAB; if you do not set the FB$SUP mask, and you specify a file that 
already exists, the CREATE operation returns an error completion and 
does not create the new file. 
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Temporary or Marked-for-Delete File 

If you want the created file to be a temporary file (one that has no 
directory entry) , set the FB$TMP mask in the 1-word FOP field of the 
FAB; if you do not set the FB$TMP mask, the created file has a 
directory entry. 

If you want the created file to be deleted when it is closed, set the 
FB$MKD mask in the 1-word FOP field of the FAB; this causes the 
operating system to delete the file when it has no accessing programs. 
If you do not set the FB$MKD mask, the created file is not marked for 
deletion. 

If you want the created file to be a temporary file that is marked for 
deletion, set the FB$TMD mask in the 1-word FOP field of the FAB; the 
FB$TMD mask includes the bits for both the FB$TMP and the FB$MKD 
masks. 



File Protection 

Specify the protection for the created file in the 1-word PRO field of 
the PRO block; if you supply no PRO block, the operating system uses 
its default file protection. 

File Organization 

Specify a file organization code in the 1-byte ORG field of the FAB. 
The symbols for file organization codes are: 

FB$IDX Indexed file organization 
FB$REL Relative file organization 
FB$SEQ Sequential file organization 

Record Format 

Specify the record format code in the 1-byte RFM field of the FAB. 
The symbols for record format codes are: 

FB$FIX Fixed-length record format 

FB$STM Stream record format 

FB$UDF Undefined record format 

FB$VAR Variable-length record format 

FB$VFC VFC record format 

If you specify VFC record format (FB$VFC code in the RFM field) , 
specify the size (in bytes) of the VFC header field in the 1-byte FSZ 
field of the FAB; if you specify 0, the CREATE operation uses the 
value 2. 

Blocked Records 

If you are creating a sequential disk file, and if you want the file 
to contain blocked records (records that cannot span block 
boundaries) , set the FB$BLK mask in the 1-byte RAT field of the FAB; 
if you do not set the FB$BLK mask, records can span block boundaries. 
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If you are creating a relative or indexed file, the FB$BLK mask has no 
effect on storage of records in the file. However, this mask will be 
preserved and returned on OPEN operations. The FB$BLK mask is ignored 
for files on unit-record devices. 



Note that records are always blocked in a magtape file, regardless 
the PB$BLK setting. 



of 



Record-Output Handling 

Specify a record-output mask in the 1-byte RAT field of the FAB. This 
record-output attribute controls the handling of records that are 
output to a unit-record device: 



"FORTRAN-style record-output specifies 
carriage-control handling. 



FORTRAN-style 



• Carriage-return record-output specifies that a prefixed 
linefeed and a suffixed carriage-return must be added to each 
record on output to a print device. 

• Print-format record-output specifies that the file is in print 
format. This format is allowed only for files with VFC 
records for which the fixed header size for each record is 
or 2 bytes. (RMS-11 treats a header size of as if you had 
specified 2.) 

When records from the file are written directly to a 
unit-record device, RMS-11 interprets the first byte of the 
VFC header as a prefix for the record and the second byte of 
the header as a suffix for the record. RMS-11 further 
interprets the prefix/suffix control bytes as follows: 

If the top bit of the control byte is clear, the entire byte 
is used as a count of the number of carriage return/line feed 
pairs with which to prefix or suffix the record. 



If the top bit of the control byte is set, the low 5 
the byte are used as the prefix or suffix character. 



bits of 



If you specify none of these attributes, records are output to 
unit-record devices without special handling. 

If you are creating a file on a device other than a unit-record 
device, the record output mask has no effect on storage of records in 
the file. However, this mask will be preserved and returned on OPEN 
operations . 

The symbols for record-output masks are: 

FB$CR Add CRLF to print record (LF-record-CR) 

FB$FTN FORTRAN-style carriage-control character in record 

FB$PRN VFC print record handling 

Record Size 

Specify the record size (in bytes) in the 1-word MRS field of the FAB 
(unless you have specified undefined record format) . For fixed-length 
records, the CREATE operation uses this value as the record size; for 
variable-length records, the CREATE operation uses this value as the 
maximum record size; for VFC records, the CREATE operation uses this 
value as the maximum size of the variable portion of each record. 
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If you specify a nonzero value in the MRS field, RMS-11 checks the 
size of each record written to the file against the MRS-field value, 
and returns an error completion if the record size is inappropriate; 
if you specify in the MRS field, RMS-11 does not check record sizes 
against the MRS-field value. 

Maximum Record Number 

If you specify relative file organization (FB$REL value in the ORG 
field) , specify the maximum record number in the 2-word MRN field of 
the FAB. If you specify a nonzero value in the MRN field, RMS-11 
checks the record number of each record written to the file against 
the MRN-field value, and returns an error completion if the record 
number is too large; if you specify in the MRN field, RMS-11 does 
not check record numbers against the MRN-field value. 

Private Buffer Pool 

If you want the CREATE operation to use a private buffer pool instead 
of the central buffer pool, specify the address of the (word-aligned) 
private buffer pool in the 1-word BPA field of the FAB, and its size 
(in bytes) in the 1-word BPS field of the FAB; this size must be a 
multiple of 4. 

If you specify in either the BPA field or the BPS field, the CREATE 
operation uses the central buffer pool. 

The pool that the CREATE operation uses is also used by the DISPLAY 
and EXTEND operations, and by stream and record operations while the 
file is open. 

Logical Channel 

Specify the logical channel for the CREATE operation in the 1-byte LCH 

field of the FAB. The logical channel number must not be the same as 

the logical channel number for any already-open file, and must not be 
0. 

The logical channel that the CREATE operation uses is also used by the 
DISPLAY and EXTEND operations, and by stream and record or block 
operations while the file is open. 

Retrieval Pointers 

Specify the number of retrieval pointers for the open file in the 
1-byte RTV field of the FAB. If you specify 0, the CREATE operation 
uses the operating system default; if you specify -1, the CREATE 
operation maps as much of the file as possible. 
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Requested Access 

Specify one or more requested-access masks in the 1-byte FAC field of 
the FAB. This mask determines the access that the creating program 
has while the file is open. Regardless of what you specify, the 
CREATE operation includes the mask FB$PUT (for record access) or 
FB$WRT (for block access) . The symbols ' for requested-access masks 
are: 

FB$DEL Request find/get/delete access 

FB$GET Request find/get access 

FB$PUT Request put access 

FB$REA Request block read access 

FB$TRN Request f ind/get/truncate access 

FB$UPD Request find/get/update access 

FB$WRT Request block write access 

Note that FB$REA and FB$WRT override any record access requested. 

Access Sharing 

Specify the kinds of access that your program is willing to share with 
other programs by setting an access-sharing mask in the 1-byte SHR 
field of the FAB. The symbols for access-sharing masks are: 

FB$GET Share find/get access 

FB$NIL No access sharing 

FB$WRI Share find/get/put/update/delete access 

FB$UPI Share any access (user-provided interlock) 

The kinds of access sharing are: 

• Shared read access 

Your program is willing to allow other programs to read the 
file, but not to write it. 

• Shared write access 

Your program is willing to allow other programs to both read 
and write the file. Shared write access is not allowed for a 
sequential file unless the file has undefined record format 
and your program opens the file for block access; shared 
write access is also not allowed for a relative or indexed 
file that your program opens for block access. In such cases, 
RMS-11 automatically converts the shared write access 
specification to a shared read access specification 
internally. 

• No shared access 

Your program is not willing to allow other programs to either 
read or write the file. RMS-11 does, however, allow other 
programs to read the file unless your program also requests 
some form of write access (which is always the case for 
CREATE) . 

User-provided interlocking 

Your program and other cooperating programs define and enforce 
their own access interlocking; RMS-11 does not check access 
sharing. User-provided interlocking is allowed only for 
sequential disk files; otherwise, the FB$UPI mask is ignored 
(but other masks are honored) . 
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Deferred Writing 

If you want deferred buffer writing for the open file, set the FB$DFW 
mask in the 1-word FOP field of the FAB; This means that RMS-11 does 
not necessarily write its buffers during a write-type operation 



(DELETE, PUT, or UPDATE) 



but instead writes buffers only when it 



needs them for other operations (or when 
FLUSH operation for the stream) . 



your program executes the 



If you do not set the FB$DFW mask, the DELETE, PUT, and UPDATE 
operations write buffers to the file immediately. 

Note that record operations always use a form of deferred buffer 
writing for sequential files, and that block operations never use 
deferred buffer writing. Therefore you need only decide whether to 
use deferred writing for a record stream to a relative or indexed 
file. 

File Locking 

If you want the file to remain unlocked even if it is closed 

abnormally, set the FB$DLK mask in the 1-word FOP field of the FAB; 

if you do not set the FB$DLK mask, the operating system locks the file 
if it is closed abnormally. 

Magtape Block Size 

If you are creating a magtape file, specify the block size (in 

characters) for the file in the 1-word BLS field of the FAB. If you 

specify 0, RMS-11 uses the default block size for the device. If you 
specify a nonzero value, it must be in the range 18 through 8192. 

Magtape Positioning 

You can position a magtape file on its magtape. To position the file 
at the beginning of the magtape (overwriting all files on the tape) , 
set the FB$RWO mask in the 1-word FOP field of the FAB. To position 
the file at the end of the last-closed file (overwriting any following 
files) , set the FB$P0S mask in the 1-word FOP field of the FAB. If 
you set neither of these masks, the CREATE operation positions the 
file at the end of the last file on the magtape (overwriting nothing) . 

Rewinding Magtape on Close 

If you want the magtape rewound when the created file is closed, set 
the FB$RWC mask in the 1-word FOP field of the FAB. If you do not set 
this mask, the magtape will not be rewound on close unless you set the 
FB$RWC mask for the CLOSE operation. Note, however, that if you set 
the FB$RWC mask for the CREATE operation, the magtape will be rewound 
even if you do not set the FB$RWC mask for the CLOSE operation. 
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Single-Area Unlocated File 

If you want the created file to have only one area, and if you do not 
want to place the area at a specific location on disk, then you supply 
no ALL blocks for the CREATE operation, but rather specify the 
following file attributes in FAB fields (as described in sections 
below) : 

• File allocation size 

• Default file extension size 

• File bucket size 

• File contiguity 

Multiarea or Located File 

If you want to place the created file at a specific location on disk, 
or if you want a created indexed file to have more than one area, then 
you supply ALL blocks for the CREATE operation and you specify the 
following area attributes in ALL block fields (as described in 
sections below) : 

• Area allocation size 

• Default area extension size 

• Area bucket size 

• Area contiguity 

• Area alignment 

• Area location 

Specify the area number for each area in the 1-byte AID field of the 
ALL block for the area. 

Sequential and relative files are permitted to have only a single 
area: area 0. Thus, for these files, the information in the (single) 
ALL block describes the file as a whole, overriding any corresponding 
information in the FAB. 

Similarly, block-accessed indexed files are treated without regard for 

their internal (logical) structure. In this case, only a single ALL 

block is permitted, and its contents describe the file as a whole, 
overriding any corresponding information in the FAB. 

Symmetric treatment of ALL blocks by the OPEN operation facilitates 
block-access COPY operations, which are independent of file 
organization . 

Allocation Size 

For a single-area unlocated file, specify the file allocation size (in 
blocks) in the 2-word ALQ field of the FAB. For a multiarea or 
located file, specify the area allocation size (in blocks) in the 
2-word ALQ field of the ALL block for each area. 
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Default Extension Size 

For a single-area unlocated file, specify the default extension size 
(in blocks) for the file in the 1-word DEQ field of the FAB. For a 
multiarea or located file, specify the default extension size (in 
blocks) for each area in the 1-word DEQ field of the ALL block for the 
area . 

Bucket Size (Relative or Indexed File) 

For a single-area unlocated file, specify the bucket size (in blocks) 
for the file in the 1-byte BKS field of the FAB. For a multiarea or 
located file, specify the bucket size (in blocks) for each area in the 
1-byte BKZ field of the ALL block for the area. 

The largest allowed bucket size is 32 blocks; the smallest is 0. If 
you specify a bucket size of 0, the CREATE operation uses 1-block 
buckets for the file or area. 

Area Location 

If you want to place an area at a particular location on disk, specify 
an alignment mask in the 1-byte ALN field of the ALL block for the 
area. Logical block alignment places the area at a specified logical 
block; virtual block alignment (not allowed for- area 0) places the 
area near a specified virtual block. If you specify no alignment 
mask, the CREATE operation places the area at any convenient location. 
The symbols for alignment masks are: 

XB$LBN Logical block alignment 
XB$VBN Virtual block alignment 

Specify the number of the logical block or virtual block in the 2-word 
LOC field of the ALL block for the area. 

If you do not want the file to be created unless the specified area 
location is available, set the XB$HRD mask in the 1-byte AOP field of 
the ALL block for the area. If you do not set this mask, the CREATE 
operation creates the file even if it must place the area at an 
alternate location. Note that hard location at a virtual block 
location is illegal. 

The CREATE operation creates areas by extending the file if either of 
the following is true: 

• You specify placement for areas other than area (in which 
case the CREATE operation ignores the FB$CTG mask) . 

• You specify contiguity in one or more ALL blocks, but not in 
the FAB for the file. 

Otherwise the CREATE operation creates the entire file as a single 
operation, and, if you specified contiguity in the FAB, creates the 
entire file as a single contiguous extent. 



5-17 



OPERATION MACRO DESCRIPTIONS 
$CREATE MACRO 



Contiguity 



If you want a file to be contiguous, set the FB$CTG mask in the 1-word 
FOP field of the FAB and (for a multiarea file) do not specify disk 
location for any area except (optionally) area 0; if the CREATE 
operation cannot create a contiguous file, it returns an error 
completion; if you do not set this mask, the CREATE operation does 
not attempt to create a contiguous file. 

If you want an area of a multiarea or located file to be contiguous, 
set the XB$CTG mask in the 1-byte AOP field of the ALL block for the 
area. If you set this mask and the CREATE operation cannot create a 
contiguous area, it returns an error completion; if you do not set 
this mask, the CREATE operation does not attempt to create a 
contiguous area. 

Indexes 

If you specify indexed file organization (FB$IDX value in the ORG 
field) , you must supply at least one KEY block for the CREATE 
operation, unless you are using block access (in which case, any KEY 
blocks are ignored) . Each KEY block you supply defines one index for 
the created file. 

Specify the reference number for each index in the 1-byte REF field of 
the KEY block for the index. Specify for the primary index, 1 for 
the first alternate index, and so forth. Chain KEY blocks so that the 
reference numbers are in consecutive order, and so that there are no 
intervening XABs of other types (ALL, DAT, PRO, or SUM blocks) . 

Key Name 

If you want to define a key name for the index, place the key name 
string in a 32-character buffer. Specify the address of this buffer 
in the 1-word KNM field of the KEY block for the index. If you 
specify in the KNM field, the index has no key name. 

Index Key Data Type 

Specify a key data type code in the 1-byte DTP field of the KEY block 
for each index. The symbols for key data type codes are: 

XB$BN2 16-bit unsigned integer 

XB$BN4 32-bit unsigned integer 

XB$IN2 15-bit signed integer 

XB$IN4 31-bit signed integer 

XB$PAC Packed decimal number 

XB$STG String 

Key Segments 

Specify the size and position of each key segment in the 8-byte SIZ 
field of the KEY block and the 8-word POS field of the KEY block for 
the index. (Only a string key can have more than one segment.) 
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The first byte of the SIZ field is for the size (in^ bytes^ of^the 

foi 

the remaining byte._ __ , 

check segment sizes after the first it encounters in the SIZ field.) 

The first word of the POS field is for the position of the firs t key 
segment, the second word is for the second segment, and so forth. If 
the key has fewer than eight segments, the CREATE operation ignores 
the remaining words of the POS field. (The first position in a record 
is position 0.) 

Key Changes 

For an alternate index, if you want to allow the key to change during 
update operations, set the XB$CHG mask in the 1-byte FLG field of the 
KEY block and the XB$DUP mask in the 1-byte FLG field of the KEY block 
for the index; if you do not set these masks, RMS- 11 returns an error 
if a program attempts to change the value of a record key during 
updating. 

Key Duplications 

If you want to allow duplicate keys in an index, set the XB$DUP mask 
in the 1-byte FLG field of the KEY block for the index. If you do not 
set this mask, RMS-11 returns an error if a program attempts to insert 
or update a record that would create a duplicate record key. Note 
that the XB$DUP mask must be set if record keys in the index are to be 
changeable during update. 

Null Keys 

If you want to omit null keys from an alternate index, set the XB$NUL 
mask in the 1-byte FLG field of the KEY block for the index, and (for 
a string key) specify the null character for the key in the 1-byte NUL 
field of the KEY block (the null value for a nonstring key is 0) . 

If you do not set the XB$NUL mask, all keys are included in the index; 
if you set the XB$NUL mask, a nonstring key with a value or a string 
key with an all-null value will not appear in that alternate index. 

Index Areas 

Specify areas for the data records and for the levels of the index: 

• The area for data records in the 1-byte DAN field of the KEY 
block 

• The area for the lowest index level in the 1-byte LAN field of 
the KEY block 

• The area for higher index levels in the 1-byte IAN field of 
the KEY block 

Note that the bucket sizes of the LAN and IAN areas of a given index 
must be identical. 
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Bucket Fill Numbers 



Bucket fill numbers guide the PUT and UPDATE operations in deciding 
how many records to place in each bucket. A bucket fill number of 
is usually appropriate, and specifies that buckets should be filled 

completely. 

A nonzero bucket fill number specifies the number of bytes that should 
be filled in each bucket. If the specified bucket fill number is less 
than half the bucket size, it is rounded up to half the bucket size; 
if the specified number is more than the bucket size, it is rounded 
down to the bucket size. 

Specify the fill numbers for data buckets and index buckets: the fill 
number for data buckets in the 1-word DFL field of the KEY block, and 
the fill number for index buckets in the 1-word IFL field of the KEY 
block. 

Longest Record Length 

If you specify block access for the created file, and you plan to copy 
an existing file into the new file, you can specify the length of the 
longest record in the new file in the 1-word LRL field of the FAB. 

RETURNED VALUES 

Internal File Identifier 

The CREATE operation writes an internal file identifier in the 1-word 
IFI field of the FAB. (The CLOSE operation clears the internal file 
identifier .) 

The CLOSE, CONNECT, DISPLAY, and EXTEND operations read the internal 
file identifier; do not alter the IFI field while the file is open. 

Device Characteristics 

The CREATE operation returns device characteristics as masks in the 
1-byte DEV field of the FAB. The device characteristics are: 

• Printer or terminal (indicated by the set FB$CCL mask in the 
1-byte DEV field of the FAB and the set FB$REC mask in the 
1-byte DEV field of the FAB; for a terminal, the FB$TRM mask 
in the 1-byte DEV field of the FAB is also set); RMS-11 
treats a printer or terminal as a unit-record device. 

• Disk, DECtape, or DECTAPE II (indicated by the set FB$MDI mask 
in the 1-byte DEV field of the FAB); RMS-11 treats a disk, 
DECtape, or DECTAPE II as a disk device. 



• 



Unit-record device (indicated by the set FB$REC mask in the 
1-byte DEV field of the FAB) . 

Non-ANSI magtape or cassette tape (indicated by the set FB$SDI 
mask in the 1-byte DEV field of the FAB and the set FB$REC 
mask in the 1-byte DEV field of the FAB) ; RMS-11 treats a 
non-ANSI magtape or a cassette tape as a unit-record device. 

ANSI-format magtape (indicated by the set FB$SQD mask in the 
1-byte DEV field of the FAB) . 
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Device, Directory, and File Identifiers 

If you supply a NAM block, the CREATE operation writes a device 
identifier in the 2-word DVI field of the NAM block, a directory 
identifier in the 3-word DID field of the NAM block, and a file 
identifier in the 3-word FID field of the NAM block. 



and 



Expanded String 

If you specify a buffer for the expanded string for the file (ESA 
ESS fields in the NAM block) , the CREATE operation writes the file 
specification for the created file in this buffer, and writes the 
length (in bytes) of the specification string in the 1-byte ESL field 
of the NAM block. 

File Specification Characteristics 

The CREATE operation sets masks in the 1-word FNB field of the NAM 
block to show which file specification elements were present in the 
file string and default string. These masks and their meanings are: 

NB$NOD Node in file string or default string 

NB$DEV Device in file string or default string 

NB$DIR Directory in file string or default string 

NB$QUO Quoted string in file string or default string 

NB$NAM File name in file string or default string 

NB$TYP File type in file string or default string 

NB$VER File version in file string or default string 

NB$WDI Wildcard directory in file string or default string 

NB$WNA Wildcard file name in file string or default string 

NB$WTY Wildcard file type in file string or default string 

NB$WVE Wildcard file version in file string or default string 

Wildcarding 

The CREATE operation clears the NB$WCH mask in the 1-word FNB field of 
the NAM block; this shows that no wildcard context exists after the 
CREATE operation. It also clears the 1-byte RSL field of the NAM 
block to show that no resultant string was returned. 

Extension Sizes 

The CREATE operation returns the size (in blocks) of each allocation 
it makes. If you created only area using FAB fields, the CREATE 
operation writes the size of the allocation in the 2-word ALQ field of 
the FAB. If you created areas using ALL blocks, the CREATE operation 
writes the size of each area allocation in the 2-word ALQ field of the 
ALL block for the area. 

Completion Status and Value 

The CREATE operation returns completion status in the 1-word STS fi el <3 
of the FAB and returns a completion value in the 1-word STV field of 
the FAB. Appendix A lists completion status symbols and values. 
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CHECKLISTS 



Table 5-5 lists control block fields that are input to the CREATE 
operation. Table 5-6 lists control block fields that are output by 
the CREATE operation. 



Table 5-5: CREATE Input Fields 



Block Field Description 



ALL AID 
ALL ALN 



ALL 
ALL 



ALL 
ALL 
ALL 
ALL 
DAT 
FAB 
FAB 
FAB 
FAB 
FAB 
FAB 
FAB 
FAB 
FAB 



ALQ 
AOP 



BKZ 
DEQ 
LOC 
NXT 
NXT 
ALQ 
BKS 
BLS 
BPA 
BPS 
DEQ 
DNA 
DNS 
FAC 



FAB FNA 
FAB FNS 
FAB FOP 



Area number 

Initial area alignment request 

XB$LBN Logical block alignment 
XB$VBN Virtual block alignment 

Initial area allocation request size (blocks) 
Area option mask 

XB$CTG Contiguous area request 
XB$HRD Area hard location request 

Area bucket size (blocks) 

Area default extension size (blocks) 

Initial area location request 

Next XAB address 

Next XAB address 

Initial file allocation request size (blocks) 

File bucket size (blocks) 

Magtape block size (characters) 

Private buffer pool address 

Private buffer pool size (bytes) 

Permanent file default extension size (blocks) 

Default string address 

Default string size (bytes) 

Requested access mask 

FB$DEL Request find/get/delete access 

FB$GET Request find/get access 

FB$PUT Request put access 

FB$REA Request block read access 

FB$TRN Request find/get/truncate access 

FB$UPD Request find/get/update access 

FB$WRT Request block write access 

File string address 
File string size (bytes) 
File processing option mask 

FB$CTG Contiguous file request 

FB$DFW Defer writing 

FB$DLK No file locking on abnormal close 

FB$FID Use information in NAM block 

FB$MKD Mark file for deletion 

FB$POS Position magtape after last-closed file 

FB$RWC Rewind magtape after closing file 

FB$RWO Rewind magtape before creating file 

FB$SUP Supersede existing file 

FB$TMD Temporary file, mark for deletion 

FB$TMP Temporary file 



(Continued on next page) 
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Table 5-5 (Cont.) : CREATE Input Fields 



Block Field Description 



FAB FSZ 

FAB LCH 

FAB LRL 

FAB MRN 

FAB MRS 

FAB NAM 

FAB ORG 



FAB 



RAT 



FAB 



RFM 



Fixed control area size for VFC records (bytes) 

Logical channel number 

Longest record length 

Maximum record number 

Maximum record size (bytes) 

NAM block address 

File organization code 

FB$IDX Indexed file organization 
FB$REL Relative file organization 
FB$SEQ Sequential file organization 

Record handling mask 

FB$BLK Blocked records 

FB$CR Add CRLF to print record (LF-record-CR) 

FB$FTN FORTRAN-style carriage-control character in 

record 
FB$PRN VFC print record handling 

Record format code 



FB$FIX Fixed-length record format 

FB$STM Stream record format 

FB$UDF Undefined record format 

FB$VAR Variable-length record format 

FB$VFC VFC record format 



FAB RTV Retrieval pointer count 
FAB SHR Shared access mask 



FB$GET Share find/get access 

FB$NIL No access sharing 

FB$WRI Share find/get/put/update/delete access 

FB$UPI Share any access (user-provided interlock) 



FAB 
KEY 
KEY 
KEY 



XAB 
DAN 
DFL 
DTP 



XAB address 

Data area number 

Data bucket fill factor 

Key data type code 

XB$BN2 16-bit unsigned integer 

XB$BN4 32-bit unsigned integer 

XB$IN2 15-bit signed integer 

XB$IN4 31-bit signed integer 

XB$PAC Packed decimal number 

XB$STG String 



KEY 



FLG 



KEY 
KEY 
KEY 
KEY 



IAN 
IFL 
KNM 
LAN 



Index option mask 

XB$DUP Duplicate record keys allowed 
XB$CHG Record key changes allowed on update 
XB$NUL Null record keys not indexed 

Higher level index area number 
Index bucket fill factor 
Key name buffer address 
Lowest index level area number 



(Continued on next page) 
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Table 5-5 (Cont.)* CREATE Input Fields 



Block Field Description 



KEY 


NUL 


KEY 


NXT 


KEY 


POS 


KEY 


REF 


KEY 


SIZ 


NAM 


ESA 


NAM 


DID 


NAM 


DVI 


NAM 


ESS 


PRO 


NXT 


PRO 


PRO 


SUM 


NXT 



Null key character 

Next XAB address 

Key segment positions 

Index reference number 

Key segment sizes (bytes) 

Expanded string buffer address 

Directory identifier 

Device identifier 

Expanded string buffer size (bytes) 

Next XAB address 

File protection code 

Next XAB address 



Table 5-6: CREATE Output Fields 



Block Field Description 



ALL ALQ 
FAB ALQ 
FAB DEV 



FAB 
FAB 
FAB 
NAM 
NAM 
NAM 
NAM 
NAM 



IFI 
STS 
STV 
DID 
DVI 
ESL 
FID 
FNB 



Initial area allocation size (blocks) 
Initial file allocation size (blocks) 
Device characteristic mask 

FB$CCL Carriage-control device 

FB$MDI Multidirectory device 

FB$REC Record-oriented device 

FB$SDI Single-directory device 

FB$SQD Sequential device 

FB$TRM Terminal device 

Internal file identifier 

Completion status code 

Completion status value 

Directory identifier 

Device identifier 

Expanded string length (bytes) 

File identifier 

File specification mask 



NB$NOD 
NB$DEV 
NB$DIR 
NB$QUO 

NB$NAM 
NB$TYP 
NB$VER 

NB$WDI 

NB$WNA 

NB$WTY 

NB$WVE 

NB$WCH 



Node in file string or default string 
Device in file string or default string 
Directory in file string or default string 
Quoted string in file string or default 
string 

File name in file string or default string 
File type in file string or default string 
File version in file string or default 
string 

in 



Wildcard directory 

default string 

Wildcard file name 

default string 

Wildcard file type 

default string 

Wildcard file version in 

default string 

Wildcard context established (cleared) 



in 



in 



file 
file 
file 
file 



string 
string 
string 
string 



or 



or 



or 



NAM 



RSL 



Resultant string length (bytes) (cleared) 
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5.4 $DELETE MACRO 

The $DELETE macro calls the DELETE operation routine to remove a 
record from a relative or indexed file. The target of the DELETE 
operation is the current record. The current record must be locked; 
it was automatically locked when the current-record context was set, 
but you must not have unlocked it with a FREE operation. 

If the stream has no current-record context, or if the current record 
is not locked, the DELETE operation returns an error completion. 

FORMAT 

The format for the $DELETE is: 

$DELETE rabaddr [ , [erraddr] [ ,sucaddr] ] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 

CONTROL BLOCKS 

You must supply a RAB for the DELETE operation. 

OPTIONS 



Internal Stream Identifier 

The DELETE operation reads the internal stream identifier 
1-word ISI field of the RAB. 



from the 



Fast Deletion (Indexed File) 

If the file is an indexed file, and if its alternate indexes allow 
duplicate keys, then you can speed up the DELETE operation by using 
the fast-deletion procedure. However, this procedure is faster 
because it deletes only those alternate index pointers that it must; 
future retrieval operations may be slowed by the presence of undeleted 
alternate index pointers. 

To use the fast-deletion procedure with the DELETE operation, set the 
RB$FDL mask in the 1-word ROP field of the RAB. If you do not set 
this mask, the DELETE operation does not use the fast-deletion 
procedure. 

Asynchronous Operation 

If you want to execute the DELETE operation asynchronously, set the 
RB$ASY mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the DELETE operation executes synchronously. (Your program 
must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 
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STREAM CONTEXT 



The current-record context after a DELETE operation is undefined; the 
next-record context is unchanged. 



RETURNED VALUES 



Completion Status and Value 

The DELETE operation returns completion status in the 1-word STS field 
of the RAB and returns a completion value in the 1-word STV field of 
the RAB. Appendix A lists completion status symbols and values. 

CHECKLISTS 

Table 5-7 lists control block fields that are input to the DELETE 
operation. Table 5-8 lists control block fields that are output by 
the DELETE operation. 



Table 5-7: DELETE Input Fields 
Block Field Description 



RAB ISI Internal stream identifier 
RAB ROP Record processing option mask 

RB$ASY Asynchronous operation 
RB$FDL Fast deletion 



Table 5-8: DELETE Output Fields 



Block Field Description 



RAB STS Completion status code 
RAB STV Completion status value 
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5.5 $DISCONNECT MACRO 

The $DISCONNECT macro calls the DISCONNECT operation routine to 
terminate a stream and disconnect it, releasing the internal resources 
it was using. The stream context is lost; you cannot reestablish the 
same stream context by reconnecting the stream with the CONNECT 
operation. 

FORMAT 

The format for the $DISCONNECT is: 

$DISCONNECT rabaddr [ , [erraddr ] [,sucaddr]] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 

CONTROL BLOCKS 

You must supply a RAB for the DISCONNECT operation. 

OPTIONS 

Internal Stream Identifier 

The DISCONNECT operation reads the internal stream identifier from the 
1-word ISI field of the RAB. 

Asynchronous Operation 

If you want to execute the DISCONNECT operation asynchronously, set 
the RB$ASY mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the DISCONNECT operation executes synchronously. (Your 
program must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 

STREAM CONTEXT 

The DISCONNECT operation terminates the stream; therefore there is no 
stream context after the DISCONNECT operation. 

RETURNED VALUES 

Internal Stream Identifier (Cleared) 

The DISCONNECT operation clears the internal stream identifier from 
the 1-word ISI field of the RAB. 

Completion Status and Value 

The DISCONNECT operation returns completion status in the 1-word STS 

field of the RAB and returns a completion value in the 1-word STV 

field of the RAB. Appendix A lists completion status symbols and 
values . 
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CHECKLISTS 



Table 5-9 lists control block fields that are input to the DISCONNECT 
operation. Table 5-10 lists control block fields that are output by 
the DISCONNECT operation. 

Table 5-9: DISCONNECT Input Fields 
Block Field Description 

RAB ISI Internal stream identifier 
RAB ROP Record processing option mask 

RB$ASY Asynchronous operation 



Table 5-10: DISCONNECT Output Fields 



Block Field Description 



RAB ISI Internal stream identifier 
RAB STS Completion status code 
RAB STV Completion status value 
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5.6 $DI SPLAY MACRO 

The $DISPLAY macro calls the DISPLAY operation routine to write values 
into control block fields. The DISPLAY operation does not alter the 
file in any way. 

When you use the OPEN operation to open a file, you might not know how 
many areas or how many indexes the file has. If, however, you supply 
a SUM block for the OPEN operation, the OPEN operation writes the 
number of areas and number of keys (indexes) in its fields. You can 
then supply ALL blocks and KEY blocks so that the DISPLAY operation 
can fill their fields with values describing the file areas and 
indexes . 



FORMAT 

The format for the $DISPLAY is: 

$DISPLAY f abaddr [ , [erraddr] [ ,sucaddr] ] 

where f abaddr is the address of the FAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 

CONTROL BLOCKS 

You must supply a FAB for the DISPLAY operation. 

If the file is an indexed file, for each ALL block that you supply, 
the DISPLAY operation fills its fields with values describing the 
corresponding area (if any) of the file. You need not supply an ALL 
block for every area of the file. Note that if the file was opened 
for block access, no information is returned in ALL blocks. 

For each KEY block that you supply, the DISPLAY operation fills its 
fields with values describing the corresponding index (if any) for the 
file. You need not supply a KEY block for every index of the file. 
Note that if the file was opened for block access, no information is 
returned in KEY blocks. 

If you supply a PRO block for a disk file, the DISPLAY operation fills 
its fields with values showing the owner and protection for the file. 

If you supply a DAT block for a disk file, the DISPLAY operation fills 
its fields with values showing the creation date, expiration date, 
revision date, and revision number for the file. 

If you supply a SUM block for a relative or indexed file, the DISPLAY 
operation fills its fields with values showing the number of areas and 
indexes for the file, and with its prologue version number. (If you 
are opening the file for block access, the DISPLAY operation returns 
the number of areas and number of keys as 0, and does not return the 
prologue version number.) 

To supply XABs (ALL, DAT, KEY, PRO, and SUM blocks) for the DISPLAY 
operation, specify the address of the first XAB in the 1-word XAB 
field of the FAB; specify the address of the next XAB (if any) in the 
1-word NXT field of each XAB; specify in the NXT field of the last 
XAB. 
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All KEY blocks must be together in the chain of XABs , and must be in 
ascending order (by the index reference number in the 1-byte REF field 
of the KEY block) ; the index reference numbers need not be 
consecutive. 

All ALL blocks must be together in the chain of XABs, and must be in 
ascending order (by the area identifier in the 1-byte AID field of the 
ALL block) ; the area identifiers need not be consecutive. 

Multiple DAT, PRO, or SUM XABs are illegal. 
OPTIONS 

Internal File Identifier 

The DISPLAY operation reads the internal file identifier from the 
1-word IFI field of the FAB. This is the value that was written when 
the file was opened by the CREATE or OPEN operation. 

Key Name Buffer 

If you want the key name string for an index returned to a buffer, 
supply a KEY block for the index; specify the address of a 32-byte 
buffer in the 1-word KNM field of the KEY block. If you do not supply 
a KEY block for an index, or if you specify in its KNM field, the 
DISPLAY operation does not return the key name string. 

STREAM CONTEXT 

The DISPLAY operation does not affect stream context. 

RETURNED VALUES 

Area Descriptions 

For each ALL block that you supply, the DISPLAY operation writes a 
description in its fields of the corresponding area of the file. Area 
is described in the ALL block containing in its AID field; area 1 
is described in the ALL block containing 1 in its AID field; and so 
forth. 

The DISPLAY operation writes three sizes for a file area: the size 
(in blocks) of the unused portion of the area in the 2-word ALQ field 
of the ALL block, the default area extension size (in blocks) in the 
1-word DEQ field of the ALL block, and the area bucket size (in 
blocks) in the 1-byte BKZ field of the ALL block. 

The DISPLAY operation clears the 1-byte AOP field of the ALL block and 
the 1-byte ALN field of the ALL block. 

Key Descriptions 

For each KEY block that you supply, the DISPLAY operation writes a 
description in its fields of the corresponding index of the file. The 
primary index is described in the KEY block containing in its REF 
field; the first alternate index is described in the KEY block 
containing 1 in its REF field; and so forth. 
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The DISPLAY operation writes the key data type code in the 1-byte DTP 
field of the KEY block. The symbols for key data type codes are: 

XB$BN2 16-bit unsigned integer 

XB$BN4 32-bit unsigned integer 

XB$IN2 15-bit signed integer 

XB$IN4 31-bit signed integer 

XB$PAC Packed decimal number 

XB$STG String 

The DISPLAY operation writes key segment information for the index: 
the number of key segments in the 1-byte NSG field of the KEY block, 
and the total key size (sum of segments, in bytes) in the 1-byte TKS 
field of the KEY block. 

The DISPLAY operation writes the sizes of key segments in the 8-byte 
SIZ field of the KEY block. The size (in bytes) of the first key 
segment is in the first byte of the SIZ field, the size of the second 
segment is in the second byte of the SIZ field, and so forth. If the 
key has fewer than eight segments, the first byte containing 
indicates the number of key segments. 

The DISPLAY operation writes the positions of key segments in the 
8-word POS field of the KEY block. The position (leftmost position is 
0) of the first key segment is in the first word of the POS field, the 
position of the second segment is in the second word of the POS field, 
and so forth. If the key has fewer than eight segments, the remaining 
words of the POS field contain unpredictable values. 

The DISPLAY operation writes a key-characteristics mask in the 1-byte 
FLG field of the KEY block. The symbols for key-characteristics masks 
are: 

XB$CHG Record key changes allowed on update 

XB$DUP Duplicate record keys allowed 

XB$INI No entries yet made in index 

XB$NUL Null record keys not indexed 

The DISPLAY operation writes the null-key character in the 1-byte NUL 
field of the KEY block. This character is meaningful only if the 
XB$NUL mask in the 1-byte FLG field of the KEY block is set and the 
DISPLAY operation returns the XB$STG code in the 1-byte DTP field of 
the KEY block (indicating a string key) . 

The DISPLAY operation writes area numbers for the index: the area for 
the data level in the 1-byte DAN field of the KEY block, the area for 
the lowest index level in the 1-byte LAN field of the KEY block, and 
the area for higher index levels in the 1-byte IAN field of the KEY 
block. 

The DISPLAY operation writes bucket fill numbers for the index areas: 
the fill number for the data area in the 1-word DFL field of the KEY 
block, and the fill number for the index areas in the 1-word IFL field 
of the KEY block. 

The DISPLAY operation writes bucket sizes for index areas: the data 
area bucket size (in blocks) in the 1-byte DBS field of the KEY block, 
and the index area bucket size (in blocks) in the 1-byte IBS field of 
the KEY block. 

The DISPLAY operation writes virtual block numbers for the index 
areas: the virtual block number for the first data bucket in the 
2-word DVB field of the KEY block, and the virtual block number of the 
root index bucket in the 2-word RVB field of the KEY block. 
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The DISPLAY operation writes the number of levels in the index (not 
including the data level) in the 1-byte LVL field of the KEY block. 

The DISPLAY operation writes the minimum size (in bytes) of a record 
that contains the key for the index in the 1-word MRL field of the KEY 
block. 

File Owner and Protection (Disk File) 

If the file is a disk file, and if you supply a PRO block, the DISPLAY 
operation writes the project (or group) portion of the file owner code 
in the 1-word PRJ field of the PRO block, the programmer (or member) 
portion of the file owner code in the 1-word PRG field of the PRO 
block, and the file protection code in the 1-word PRO field of the PRO 
block. 

File Dates 

If you supply a DAT block for a disk file, the DISPLAY operation 

writes four values in its fields: the creation date in the 4-word CDT 

field of the DAT block, the expiration date in the 4-word EDT field of 

the DAT block, the revision date in the 4-word RDT field of the DAT 

block, and the revision number (number of times the file has been 

write-accessed and then closed) in the 1-word RVN field of the DAT 
block. 

File Summary Information 

If you supply a SUM block, the DISPLAY operation writes three values 
in its fields: the number of file areas in the 1-byte NOA field of 
the SUM block, the number of file indexes in the 1-byte NOK field of 
the SUM block, and the prologue version number (for a relative or 
indexed file) in the 1-word PVN field of the SUM block. 

Completion Status and Value 

The DISPLAY operation returns completion status in the 1-word STS 

field of the FAB and returns a completion value in the 1-word STV 

field of the FAB. Appendix A lists completion status symbols and 

values . 



CHECKLISTS 

Table 5-11 lists control block fields that are input to the DISPLAY 
operation. Table 5-12 lists control block fields that are output by 
the DISPLAY operation. 
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Table 5-11: DISPLAY Input Fields 



Block Field Description 



ALL 


AID 


ALL 


NXT 


DAT 


NXT 


FAB 


IFI 


FAB 


XAB 


KEY 


NXT 


KEY 


KNM 


KEY 


REF 


PRO 


NXT 


SUM 


NXT 



Area number 

Next XAB address 

Next XAB address 

Internal file identifier 

XAB address 

Next XAB address 

Key name buffer address 

Index reference number 

Next XAB address 

Next XAB address 



Table 5-12: DISPLAY Output Fields 



Block Field Description 



ALL ALN 
ALL ALQ 
ALL AOP 



ALL 
ALL 
DAT 
DAT 
DAT 
DAT 
FAB 
FAB 
KEY 
KEY 
KEY 
KEY 



BKZ 
DEQ 
CDT 
EDT 
RDT 
RVN 
STS 
STV 
DAN 
DBS 
DFL 
DTP 



KEY 
KEY 



DVB 
FLG 



Area alignment mask (cleared) 
Unused area allocation size (blocks) 
Area option mask 

XB$CTG Contiguous area (cleared) 
XB$HRD Hard area location (cleared) 

Area bucket size (blocks) 

Area default extension size (blocks) 

File creation date 

File expiration date 

File revision date 

File revision number 

Completion status code 

Completion status value 

Data area number 

Data area bucket size (blocks) 

Data bucket fill factor 

Key data type code 

XB$BN2 16-bit unsigned integer 

XB$BN4 32-bit unsigned integer 

XB$IN2 15-bit signed integer 

XB$IN4 31-bit signed integer 

XB$PAC Packed decimal number 

XB$STG String 

First data bucket virtual block number 
Index option mask 

XB$CHG Record key changes allowed on update 

XB$DUP Duplicate record keys allowed 

XB$INI No entries yet made in index 

XB$NUL Null record keys not indexed 



(Continued on next page) 
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Table 5-12 (Cont.) : DISPLAY Output Fields 



Block Field Description 



Higher level index area number 

Index area bucket size (blocks) 

Index bucket fill factor 

Lowest index level area number 

Number of index levels (not including data level) 

Minimum length of record containing key (bytes) 

Key segment count 

Null key character 

Key segment positions 

Root index bucket virtual block number 

Key segment sizes (bytes) 

Total key size (sum of key segment sizes) (bytes) 

Programmer or member portion of file owner code 

Project or group portion of file owner code 

File protection code 

Number of areas 

Number of indexes 

Prologue version number 



KEY 


IAN 


KEY 


IBS 


KEY 


IFL 


KEY 


LAN 


KEY 


LVL 


KEY 


MRL 


KEY 


NSG 


KEY 


NUL 


KEY 


POS 


KEY 


RVB 


KEY 


SIZ 


KEY 


TKS 


PRO 


PRG 


PRO 


PR J 


PRO 


PRO 


SUM 


NOA 


SUM 


NOK 


SUM 


PVN 
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5.7 $ ENTER MACRO 

The $ENTER macro calls the ENTER operation routine to insert a file 
name into a directory file. 

FORMAT 

The format for the $ENTER is: 

$ENTER fabaddr [, [erraddr] [,sucaddr]] 

where fabaddr is the address of the FAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 

CONTROL BLOCKS 

You must supply a FAB for the ENTER operation. 

You must supply a NAM block for the ENTER operation. 

To supply a NAM block for the ENTER operation, specify the address of 
the NAM block in the 1-word NAM field of the FAB. 

To supply XABs (ALL, DAT, KEY, PRO, and SUM blocks) for the ENTER 
operation, specify the address of the first XAB in the 1-word XAB 
field of the FAB; specify the address of the next XAB (if any) in the 
1-word NXT field of each XAB; specify in the NXT field of the last 
XAB. 

All KEY blocks must be together in the chain of XABs, and must be in 
ascending order (by the index reference number in the 1-byte REF field 
of the KEY block) ; the index reference numbers need not be 
consecutive. 

All ALL blocks must be together in the chain of XABs, and must be in 
ascending order (by the area identifier in the 1-byte AID field of the 
ALL block) ; the area identifiers need not be consecutive. 

Multiple DAT, PRO, or SUM XABs are illegal. 
OPTIONS 

File Specification 

The ENTER operation constructs the full file specification from the 
file string, the default string (which contributes only elements not 
present in the file string) , and RMS-11 defaults (which contribute 
elements not present in either the file string or the default string) . 

RMS-11 defaults are: 

• Device — The device to which the specified logical channel is 
assigned, or SY: if the specified logical channel is not 
assigned to any device. 

Directory — The current directory for the task. 

Name, type, version — Defaulted to null. 
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The file string and the default string must not contain wildcards. 

Specify the address of the file string in the 1-word FNA field of the 

FAB. Specify the size (in bytes) of the file string in the 1-byte FNS 

field of the FAB; if you specify in the FNS field, the ENTER 
operation uses no file string. 

Specify the address of the default string in the 1-word DNA field of 

the FAB. Specify the size (in bytes) of the default string in the 

1-byte DNS field of the FAB; if you specify in the DNS field, the 
ENTER operation uses no default string. 

If you set the FB$FID mask in the 1-word FOP field of the FAB and 
supply a NAM block, the ENTER operation reads the device identifier 
from the 2-word DVI field of the NAM block; if this value is nonzero, 
the specified device overrides the device in the merged string. 

In the same circumstance, the ENTER operation reads the directory 
identifier from the 3-word DID field of the NAM block; if this value 
is nonzero, the specified directory overrides the directory in the 
merged string. 

You must provide a NAM block for the ENTER operation, and must provide 
a valid file identifier in the 3-word FID field of the NAM block. 
This identifier specifies the file for which the entry (name, type, 
and version) will be created in the target directory. 

Expanded String Buffer 

If you want the ENTER operation to return the expanded string for the 
created file, provide a buffer for the string. Specify the address of 
the expanded string buffer in the 1-word ESA field of the NAM block. 
Specify the size (in bytes) of the expanded string buffer in the 
1-byte ESS field of the NAM block; if you specify in the ESS field, 
the ENTER operation does not return the expanded string. 

Private Buffer Pool 

If you want the ENTER operation to use a private buffer pool instead 
of the central buffer pool, specify the address of the (word-aligned) 
private buffer pool in the 1-word BPA field of the FAB, and its size 
(in bytes) in the 1-word BPS field of the FAB; this size must be a 
multiple of 4. 

If you specify in either the BPA field or the BPS field, the ENTER 
operation uses the central buffer pool. 

Logical Channel 

Specify the logical channel for the ENTER operation in the 1-byte LCH 

field of the FAB. The logical channel number must not be the same as 

the logical channel number for any already-open file, and must not be 
0. 
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RETURNED VALUES 



Expanded String 

If you specify a buffer for the expanded string for the file (ESA and 
ESS fields in the NAM block), the ENTER operation writes the file 
specification for the target file in this buffer, and writes the 
length (in bytes) of the specification string in the 1-byte ESL field 
of the NAM block. 

Device Characteristics 

The ENTER operation returns device characteristics as masks in the 
1-byte DEV field of the FAB. The device characteristics are: 

• Printer or terminal (indicated by the set FB$CCL mask in the 
1-byte DEV field of the FAB and the set FB$REC mask in the 
1-byte DEV field of the FAB; for a terminal, the FB$TRM mask 
in the 1-byte DEV field of the FAB is also set); RMS-11 
treats a printer or terminal as a unit-record device. 

• Disk, DECtape, or DECTAPE II (indicated by the set FB$MDI mask 
in the 1-byte DEV field of the FAB); RMS-11 treats a disk, 
DECtape, or DECTAPE II as a disk device. 



• Unit-record device (indicated by the set FB$REC 
1-byte DEV field of the FAB) . 



mask in the 



• Non-ANSI magtape or cassette tape (indicated by the set FB$SDI 
mask in the 1-byte DEV field Of the FAB and the set FB$REC 
mask in the 1-byte DEV field of the FAB) ; RMS-11 treats a 
non-ANSI magtape or a cassette tape as a unit-record device. 

• ANSI-format magtape (indicated by the set FB$SQD mask in the 
1-byte DEV field of the FAB) . 

Device and Directory Identifiers 

The ENTER operation returns the device identifier for the target file 
in the 2-word DVI field of the NAM block and the directory identifier 
in the 3-word DID field of the NAM block. 

File Specification Characteristics 

The ENTER operation sets masks in the 1-word FNB field of the NAM 
block to show which file specification elements were present in the 
file string and default string. These masks and their meanings are: 

NB$NOD Node in file string or default string 

NB$DEV Device in file string or default string 

NB$DIR Directory in file string or default string 

NB$QUO Quoted string in file string or default string 

NB$NAM File name in file string or default string 

NB$TYP File type in file string or default string 

NB$VER File version in file string or default string 

NB$WDI Wildcard directory in file string or default string 

NB$WNA Wildcard file name in file string or default string 

NB$WTY Wildcard file type in file string or default string 

NB$WVE Wildcard file version in file string or default string 
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Wildcarding 



The ENTER operation clears the NB$WCH mask in the 1-word FNB field of 
the NAM block and the 1-byte RSL field of the NAM block; this shows 
that no wildcard context exists and that no resultant string was 
returned . 

Completion Status and Value 

The ENTER operation returns completion status in the 1-word STS field 
of the FAB and returns a completion value in the 1-word STV field of 
the FAB. Appendix A lists completion status symbols and values. 

CHECKLISTS 

Table 5-13 lists control block fields that are input to the ENTER 
operation. Table 5-14 lists control block fields that are output by 
the ENTER operation. 



Table 5-13: ENTER Input Fields 



Block Field Description 



ALL 


NXT 


DAT 


NXT 


FAB 


BPA 


FAB 


BPS 


FAB 


DNA 


FAB 


DNS 


FAB 


FNA 


FAB 


FNS 


FAB 


FOP 



FAB 


LCH 


FAB 


NAM 


KEY 


NXT 


NAM 


DID 


NAM 


DVI 


NAM 


ESA 


NAM 


ESS 


NAM 


FID 


PRO 


NXT 


SUM 


NXT 



Next XAB address 

Next XAB address 

Private buffer pool address 

Private buffer pool size (bytes) 

Default string address 

Default string size (bytes) 

File string address 

File string size (bytes) 

File processing option mask 

FB$FID Use information in NAM block 

Logical channel number 

NAM block address 

Next XAB address 

Directory identifier 

Device identifier 

Expanded string buffer address 

Expanded string buffer size (bytes) 

File identifier 

Next XAB address 

Next XAB address 
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Table 5-14: ENTER Output Fields 



Block Field Description 



FAB DEV Device characteristic mask 

FB$CCL Carriage-control device 

FB$MDI Multidirectory device 

FB$REC Record-oriented device 

FB$SDI Single-directory device 

FB$SQD Sequential device 

FB$TRM Terminal device 

FAB STS Completion status code 

FAB STV Completion status value 

NAM DID Directory identifier 

NAM DVI Device identifier 

NAM ESL Expanded string length (bytes) 

NAM FNB File specification mask 

NB$NOD Node in file string or default string 
NB$DEV Device in file string or default string 
NB$DIR Directory in file string or default string 
NB$QUO Quoted string in file string or default 

string 
NB$NAM File name in file string or default string 
NB$TYP File type in file string or default string 
NB$VER File version in file string or default 

string 
NB$WDI Wildcard directory in file string or 

default string 
NB$WNA Wildcard file name in file string or 

default string 
NB$WTY Wildcard file type in file string or 

default string 
NB$WVE Wildcard file version in file string or 

default string 
NB$WCH Wildcard context established (cleared) 

NAM RSL Resultant string length (bytes) (cleared) 
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5.8 $ ERASE MACRO 



The $ERASE macro calls the ERASE operation routine to erase a file and 
delete its directory entry. Note that erasing a file marks the file 
for deletion, but does not necessarily erase the file immediately; 
the file is erased when it has no accessing programs. The allocation 
for the file is released for use in other files. 

FORMAT 

The format for the $ERASE is: 

$ERASE fabaddr [ , [erraddr] [,sucaddr]] 

where fabaddr is the address of the FAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 

CONTROL BLOCKS 

You must supply a FAB for the ERASE operation. 

If you supply a NAM block and specify wildcarding, the ERASE operation 
reads the address and length of the expanded string from NAM block 
fields; if you supply a NAM block and specify erase by NAM block, the 
ERASE operation reads NAM block fields to obtain identifiers for the 
target file. 

To supply a NAM block for the ERASE operation, specify the address of 
the NAM block in the 1-word NAM field of the FAB. 

To supply XABs (ALL, DAT, KEY, PRO, and SUM blocks) for the ERASE 
operation, specify the address of the first XAB in the 1-word XAB 
field of the FAB; specify the address of the next XAB (if any) in the 
1-word NXT field of each XAB; specify in the NXT field of the last 
XAB. 

All KEY blocks must be together in the chain of XABs, and must be in 
ascending order (by the index reference number in the 1-byte REF field 
of the KEY block) ; the index reference numbers need not be 
consecutive. 

All ALL blocks must be together in the chain of XABs, and must be in 
ascending order (by the area identifier in the 1-byte AID field of the 
ALL block) ; the area identifiers need not be consecutive. 

Multiple DAT, PRO, or SUM XABs are illegal. 
OPTIONS 

File Specification (Nonwildcard ERASE Operation) 

The ERASE operation constructs the full file specification from the 
file string, the default string (which contributes only elements not 
present in the file string) , and RMS-11 defaults (which contribute 
elements not present in either the file string or the default string) . 
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RMS-11 defaults are: 

• Device — The device to which the specified logical channel is 
assigned, or SY: if the specified logical channel is not 
assigned to any device. 

• Directory — ■- The current directory for the task. 

• Name, type, version — Defaulted to null. 

The file string and the default string must not contain wildcards. 

Specify the address of the file string in the 1-word FNA field of the 

FAB. Specify the size (in bytes) of the file string in the 1-byte FNS 

field of the FAB; if you specify in the FNS field, the ERASE 
operation uses no file string. 

Specify the address of the default string in the 1-word DNA field of 

the FAB. Specify the size (in bytes) of the default string in the 

1-byte DNS field of the FAB; if you specify in the DNS field, the 
ERASE operation uses no default string. 

If you set the FB$FID mask in the 1-word FOP field of the FAB and 
supply a NAM block, the ERASE operation reads the device identifier 
from the 2-word DVI field of the NAM block; if this value is nonzero, 
the specified device overrides the device in the merged string. 

In the same circumstance, the ERASE operation reads the directory 
identifier from the 3-word DID field of the NAM block; if this value 
is nonzero, the specified directory overrides the directory in the 
merged string. 

In the same circumstance, the ERASE operation reads the file 
identifier from the 3-word FID field of the NAM block; if this value 
is nonzero, the specified file overrides any directory, name, type, 
and version elements previously obtained, and the file is erased 
without removing any directory entry that may exist for it. 

Erase by Wildcard Specification 

You can use the ERASE operation in a wildcarding program loop. (The 
NB$WCH mask in the 1-word FNB field of the NAM block will already have 
been set by an earlier PARSE operation.) 

If you set the FB$FID mask in the 1-word FOP field of the FAB, the 
file found by a previous SEARCH operation and its directory entry are 
deleted, but all fields relevant to wildcard context are preserved 
(for possible subsequent SEARCH operations) . 

If you clear the FB$FID mask in the 1-word FOP field of the FAB, the 
ERASE operation first performs an implicit SEARCH operation. (The 
input and output fields for the SEARCH operation are not described 
here and are not included in the checklists at the end of this 
section.) 

If the SEARCH operation finds a file that matches the wildcard file 
specification, the ERASE operation erases its contents and deletes its 
directory entry; if not, the ERASE operation does not erase the file 
contents or delete its directory entry, but instead passes control 
block data from the SEARCH operation (in particular, the ER$NMF 
completion status code and the cleared NB$WCH mask in the 1-word FNB 
field of the NAM block) . 
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Expanded String Buffer 

If you erase a file by its file specification, and if you want the 
ERASE operation to return the expanded string for the erased file, 
provide a buffer for the string. Specify the address of the expanded 
string buffer in the 1-word ESA field of the NAM block. Specify the 
size (in bytes) of the expanded string buffer in the 1-byte ESS field 
of the NAM block; if you specify in the ESS field, the ERASE 
operation does not return the expanded string. 

Private Buffer Pool 

If you want the ERASE operation to use a private buffer pool instead 
of the central buffer pool, specify the address of the (word-aligned) 
private buffer pool in the 1-word BPA field of the FAB, and its size 
(in bytes) in the 1-word BPS field of the FAB; this size must be a 
multiple of 4. 

If you specify in either the BPA field or the BPS field, the ERASE 
operation uses the central buffer pool. 

Logical Channel 

Specify the logical channel for the ERASE operation in the 1-byte LCH 

field of the FAB. The logical channel number must not be the same as 

the logical channel number for any already-open file, and must not be 

. 



RETURNED VALUES 

Expanded String 

If you specify a buffer for the expanded string for the file (ESA and 
ESS fields in the NAM block) , the ERASE operation writes the expanded 
string for the erased file in the buffer, and writes the length (in 
bytes) of the string in the 1-byte ESL field of the NAM block. 

Device, Directory, and File Identifiers 

If you supply a NAM block, the ERASE operation writes a device 
identifier in the 2-word DVI field of the NAM block, a directory 
identifier in the 3-word DID field of the NAM block (unless directory 
processing was bypassed due to use of the file identifier on input) , 
and a file identifier in the 3-word FID field of the NAM block. 

Device Characteristics 

The ERASE operation returns device characteristics as masks in the 
1-byte DEV field of the FAB. The device characteristics are: 

• Printer or terminal (indicated by the set FB$CCL mask in the 
1-byte DEV field of the FAB and the set FB$REC mask in the 
1-byte DEV field of the FAB; for a terminal, the FB$TRM mask 
in the 1-byte DEV field of the FAB is also set) ; RMS-11 
treats a printer or terminal as a unit-record device. 

Disk, DECtape, or DECTAPE II (indicated by the set FB$MDI mask 
in the 1-byte DEV field of the FAB); RMS-11 treats a disk, 
DECtape, or DECTAPE II as a disk device. 
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Unit-record device (indicated by the set PB$REC mask in the 
1-byte DEV field of the FAB) . 

Non-ANSI magtape or cassette tape (indicated by the set FB$SDI 
mask in the 1-byte DEV field of the FAB and the set FB$REC 
mask in the 1-byte DEV field of the FAB) ; RMS-11 treats a 
non-ANSI magtape or a cassette tape as a unit-record device. 

• ANSI-format magtape (indicated by the set FB$SQD mask in the 
1-byte DEV field of the FAB) . 

Wildcard Context 

A nonwildcard ERASE operation clears the NB$WCH mask in the 1-word FNB 
field of the NAM block and the 1-byte RSL field of the NAM block; 
this shows that no wildcarding is in progress and that no resultant 
string was returned. 

File Specification Characteristics 

The ERASE operation sets masks in the 1-word FNB field of the NAM 
block to show which file specification elements were present in the 
file string and default string. These masks and their meanings are: 

NB$NOD Node in file string or default string 

NB$DEV Device in file string or default string 

NB$DIR Directory in file string or default string 

NB$QCJO Quoted string in file string or default string 

NB$NAM File name in file string or default string 

NB$TYP File type in file string or default string 

NB$VER File version in file string or default string 

NB$WDI Wildcard directory in file string or default string 

NB$WNA Wildcard file name in file string or default string 

NB$WTY Wildcard file type in file string or default string 

NB$WVE Wildcard file version in file string or default string 

Completion Status and Value 

The ERASE operation returns completion status in the 1-word STS field 
of the FAB and returns a completion value in the 1-word STV field of 
the FAB. Appendix A lists completion status symbols and values. 

CHECKLISTS 

Table 5-15 lists control block fields that are input to the ERASE 
operation. Table 5-16 lists control block fields that are output by 
the ERASE operation. 
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Table 5-15: ERASE Input Fields 



Block Field Description 



ALL 


NXT 


DAT 


NXT 


FAB 


BPA 


FAB 


BPS 


FAB 


DNA 


FAB 


DNS 


FAB 


FNA 


FAB 


FNS 


FAB 


FOP 



FAB 


LCH 


FAB 


NAM 


KEY 


NXT 


NAM 


DID 


NAM 


DVI 


NAM 


ESA 


NAM 


ESS 


NAM 


FID 


NAM 


FNB 


PRO 


NXT 


SUM 


NXT 



Next XAB address 

Next XAB address 

Private buffer pool address 

Private buffer pool size (bytes) 

Default string address 

Default string size (bytes) 

File string address 

File string size (bytes) 

File processing option mask 

FB$FID Use information in NAM block 

Logical channel number 

NAM block address 

Next XAB address 

Directory identifier 

Device identifier 

Expanded string buffer address 

Expanded string buffer size (bytes) 

File identifier 

File specification mask 

Next XAB address 

Next XAB address 



NB$WCH 



Wildcard context established 



Table 5-16: ERASE Output Fields 



Block Field Description 



FAB 



DEV 



Device characteristic mask 



FB$CCL Carriage-control device 

FB$MDI Multidirectory device 

FB$REC Record-oriented device 

FB$SDI Single-directory device 

FB$SQD Sequential device 

FB$TRM Terminal device 

FAB STS Completion status code 

FAB STV Completion status value 

NAM DID Directory identifier 

NAM DVI Device identifier 

NAM ESL Expanded string length (bytes) 

NAM FID File identifier 



(Continued on next page) 
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Table 5-16 (Cont.): ERASE Output Fields 



Block Field Description 



NAM 



NAM 



FNB File specification mask 

NB$NOD Node in file string or default string 
NB$DEV Device in file string or default string 
NB$DIR Directory in file string or default string 
NB$QUO Quoted string in file string or default 

string 
NB$NAM File name in file string or default string 
NB$TYP File type in file string or default string 
NB$VER File version in file string or default 

string 
NB$WDI Wildcard directory in file string or 

default string 
NB$WNA Wildcard file name in file string or 

default string 
NB$WTY Wildcard file type in file string or 

default string 
NB$WVE Wildcard file version in file string or 

default string 
NB$WCH Wildcard context established 

RSL Resultant string length (bytes) 
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5.9 $ EXT END MACRO 

The $EXTEND macro calls the EXTEND operation routine to extend the 
allocation for an open file. 

FORMAT 

The format for the $EXTEND is: 

$EXTEND fabaddr [ , [erraddr] [ ,sucaddr] ] 

where fabaddr is the address of the FAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 

CONTROL BLOCKS 

You must supply a FAB for the EXTEND operation. 

For each ALL block that you supply, the EXTEND operation extends the 
corresponding area as described in the ALL block. You need not supply 
an ALL block for an area that you do not want to extend, but each 
supplied ALL block must correspond to an area in the file; this means 
that you can supply ALL blocks for areas other than area only for an 
indexed file opened for record access. 

To supply XABs (ALL, DAT, KEY, PRO, and SUM blocks) for the EXTEND 
operation, specify the address of the first XAB in the 1-word XAB 
field of the FAB; specify the address of the next XAB (if any) in the 
1-word NXT field of each XAB; specify in the NXT field of the last 
XAB. 

All KEY blocks must be together in the chain of XABs, and must be in 
ascending order (by the index reference number in the 1-byte REF field 
of the KEY block) ; the index reference numbers need not be 
consecutive . 

All ALL blocks must be together in the chain of XABs, and must be in 
ascending order (by the area identifier in the 1-byte AID field of the 
ALL block); the area identifiers need not be consecutive. 

Multiple DAT, PRO, or SUM XABs are illegal. 
OPTIONS 

Internal File Identifier 

The EXTEND operation reads the internal file identifier from the 
1-word IFI field of the FAB. This is the value written by the CREATE 
or OPEN operation that opened the file. 

Area Extended by FAB 

If you supply no ALL blocks, specify the size (in blocks) of the 
extension in the 2-word ALQ field of the FAB. 

If you want the extension to be contiguous within itself (it will not 

necessarily be contiguous with the file) , set the FB$CTG mask in the 

1-word FOP field of the FAB; if you do not set this mask, the 
extension is not necessarily contiguous within itself. 
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Areas Extended by ALL Blocks 

If you supply ALL blocks, the EXTEND operation ignores the ALQ field 
of the FAB, and extends each area specified in an ALL block. Specify 
each area to be extended by supplying an ALL block with the area 
number in the 1-byte AID field of the ALL block. Specify the size of 
the extension (in blocks) for the area in the 2-word ALQ field of the 
ALL block. 

If you want the area extension to be contiguous within itself (it will 
not be contiguous with the previous area extent) , set the XB$CTG mask 
in the 1-byte AOP field of the ALL block. If you do not set this 
mask, the extension will not necessarily be contiguous within itself. 

If you want to place the extension at a specific location, specify an 
alignment mask in the 1-byte ALN field of the ALL block; if you 
specify 0, the EXTEND operation places the extension at any convenient 
location. The symbols for alignment masks are: 

XB$LBN Logical block alignment i 

XB$VBN Virtual block alignment 

Specify the number of the logical block or virtual block in the 2-word 
LOC field of the ALL block. 

If you specify logical block alignment, and if you want the extension 
placed only at the location you specify, set the XB$HRD mask in the 
1-byte AOP field of the ALL block. If you do not set this mask, the 
EXTEND operation selects an alternate location if the specified 
location is not available. If you do set this mask, the EXTEND 
operation returns an error completion if the specified location is not 
available. 



STREAM CONTEXT 

The EXTEND operation does not affect stream context. 

RETURNED VALUES 

Extension Sizes 

The EXTEND operation returns the size (in blocks) of each extension it 
makes. If you extended only area using FAB fields, the EXTEND 
operation writes the size of the extension in the 2-word ALQ field of 
the FAB. If you extended areas using ALL blocks, the EXTEND operation 
writes the size of each area extension in the 2-word ALQ field of the 
ALL block for the area. 

Completion Status and Value 

The EXTEND operation returns completion status in the 1-word STS field 
of the FAB and returns a completion value in the 1-word STV field of 
the FAB. Appendix A lists completion status symbols and values. 

CHECKLISTS 

Table 5-17 lists control block fields that are input to the EXTEND 
operation. Table 5-18 lists control block fields that are output by 
the EXTEND operation. 
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Table 5-17: EXTEND Input Fields 



Block Field Description 



ALL 
ALL 



ALL 
ALL 



AID 

ALN 



ALQ 
AOP 



ALL 


LOC 


ALL 


NXT 


DAT 


NXT 


FAB 


ALQ 


FAB 


FOP 



FAB 


IFI 


FAB 


XAB 


KEY 


NXT 


PRO 


NXT 


KEY 


REF 


SUM 


NXT 



Area number 

Area extension alignment request 

XB$LBN Logical block alignment 
XB$VBN Virtual block alignment 

Area allocation extension request size (blocks) 
Area option mask 

XB$CTG Contiguous area extension request 
XB$HRD Area extension hard location request 

Area extension location request 

Next XAB address 

Next XAB address 

File allocation extension request size (blocks) 

File processing option mask 

FB$CTG Contiguous file extension request 

Internal file identifier 
XAB address 
Next XAB address 
Next XAB address 
Index reference number 
Next XAB address 



Table 5-18: EXTEND Output Fields 



Block Field Description 



ALL 


ALQ 


FAB 


ALQ 


FAB 


STS 


FAB 


STV 



Area allocation extension actual size (blocks) 
File allocation extension actual size (blocks) 
Completion status code 
Completion status value 
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5.10 $FIND MACRO (SEQUENTIAL ACCESS) 



The $FIND macro calls the FIND operation routine to transfer a record 
(or part of a record) from a file to an I/O buffer. The FIND 
operation transfers the entire record if the file is relative or 
indexed, or if it has blocked records; it may transfer only part of 
the record if the record spans block boundaries. The FIND operation 
does not transfer the record to a user buffer. 

The target of a sequential-access FIND operation is the next record 
(for an indexed file, the next record under the current index) . 

FORMAT 

The format for the $FIND is: 

$FIND rabaddr [ , [erraddr] [ ,sucaddr] ] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 

CONTROL BLOCKS 

You must supply a RAB for the FIND operation. 

OPTIONS 

Internal Stream Identifier 

The FIND operation reads the internal stream identifier from the 
1-word ISI field of the RAB. 

Asynchronous Operation 

If you want to execute the FIND operation asynchronously, set the 
RB$ASY mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the FIND operation executes synchronously. (Your program 
must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 

Sequential Access 

Specify the RB$SEQ code in the 1-byte RAC field of the RAB. 

STREAM CONTEXT 

The current-record context after a sequential access FIND operation is 
the found record; the next-record context is the record following the 
found record (for an indexed file, the next record under the current 
index) . If the FIND operation returns an error completion, the 
current-record context is undefined, and the next- record context is 
unchanged. 
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RETURNED VALUES 



RRN 

For a relative file or for a sequential disk file with fixed-length 
records, a sequential-access FIND operation returns the relative 
record number (RRN) for the found record in the 2-word BKT field of 
the RAB. 



RFA 

The FIND operation returns the record file address (RFA) for the found 
record in the 3-word RFA field of the RAB. 

Completion Status and Value 

The FIND operation returns completion status in the 1-word STS field 
of the RAB and returns a completion value in the 1-word STV field of 
the RAB. Appendix A lists completion status symbols and values. 

CHECKLISTS 

Table 5-19 lists control block fields that are input to the FIND 
operation. Table 5-20 lists control block fields that are output by 
the FIND operation. 

Table 5-19: FIND (Sequential Access) Input Fields 
Block Field Description 



RAB 
RAB 



RAB 



ISI 
RAC 



ROP 



Internal stream identifier 
Record access code 

RB$SEQ Sequential access 

Record processing option mask 

RB$ASY Asynchronous operation 



Table 5-20: FIND (Sequential Access) Output Fields 
Block Field Description 



RAB 


BKT 


RAB 


RFA 


RAB 


STS 


RAB 


STV 



Relative record number (RRN) 
Record file address 
Completion status code 
Completion status value 
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5.11 $FIND MACRO (KEY ACCESS) 

The $FIND macro calls the FIND operation routine to transfer a record 
(or part of a record) from a sequential disk file (with fixed-length 
records), a relative file, or an indexed file to an I/O buffer. The 
FIND operation transfers the entire record if the file is relative or 
indexed, or if it has blocked records; it may transfer only part of 
the record if the record spans block boundaries. The FIND operation 
does not transfer the record to a user buffer. 

The target of a key-access FIND operation is the record having the 
specified key (under the specified match criterion) . For a relative 
file or for a sequential disk file with fixed-length records, the key 
is a relative record number (RRN) ; for an indexed file, the key is an 
index key under the specified index. 

FORMAT 

The format for the $FIND is: 

$FIND rabaddr [ , [erraddr] [ ,sucaddr] ] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 

CONTROL BLOCKS 

You must supply a RAB for the FIND operation. 

OPTIONS 

Internal Stream Identifier 

The FIND operation reads the internal stream identifier from the 
1-word ISI field of the RAB. 

Asynchronous Operation 

If you want to execute the FIND operation asynchronously, set the 
RB$ASY mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the FIND operation executes synchronously. (Your program 
must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 

Key Access 

Specify the RB$KEY code in the 1-byte RAC field of the RAB. 

Key of Reference (Indexed File) 

Specify the key of reference in the 1-byte KRF field of the RAB. The 
key of reference is the reference number (REF field of KEY block) for 
the index you want to use for the FIND operation. 
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Key 



Specify a buffer containing the key for the record to be found: 
specify the address of the key buffer in the 1-word KBF field of the 
RAB, and specify the size of the key in the 1-byte KSZ field of the 
RAB. 

For a relative file, or for a sequential file with fixed-length 
records, specify a 4-byte binary relative record number (RRN) as the 
key, and specify the key size as or 4. 

For an indexed file, specify a key of the same type as the key for the 
current index, and specify a key size no greater than the key size for 
the current index. For a nonstring key, the specified key size must 
be the key size defined for the index (or, equivalently, 0); for a 
string key, if you specify a key size smaller than the key size for 
the index, the FIND operation searches for a record whose key begins 
with the specified partial key (under the specified key criterion) . 

Key Criterion 

Specify a key-criterion mask in the 1-word ROP field of the RAB. The 
symbols for key-criterion masks are: 

RB$KGE Greater-than-or-equal key criterion 
RB$KGT Greater-than key criterion 

If you specify the key-greater criterion, the FIND operation searches 
for the first record whose key is greater than the key you specify; 
if you specify the key-greater-or-equal criterion, the FIND operation 
searches for the first record whose key is greater than or equal to 
the key you specify; if you specify neither criterion, the FIND 
operation searches for a record whose key exactly matches the key you 
specify. (It is illegal to specify both criteria.) 

STREAM CONTEXT 

The current-record context after a key access FIND operation is the 
found record; the next-record context is unchanged. If the FIND 
operation returns an error completion, the current-record context is 
undefined, and the next-record context is unchanged. 

RETURNED VALUES 



RFA 

The FIND operation returns the record file address (RFA) for the found 
record in the 3-word RFA field of the RAB. 



RRN 

For a relative file or for a sequential disk file with fixed-length 
records, the FIND operation returns the RRN of the found record in the 
2-word BKT field of the RAB. 
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Completion Status and Value 

The FIND operation returns completion status in the 1-word STS field 
of the RAB and returns a completion value in the 1-word STV field of 
the RAB. Appendix A lists completion status symbols and values. 

CHECKLISTS 

Table 5-21 lists control block fields that are input to the FIND 
operation. Table 5-22 lists control block fields that are output by 
the FIND operation. 

Table 5-21: FIND (Key Access) Input Fields 



Block Field Description 



RAB ISI Internal stream identifier 

RAB KBF Key buffer address 

RAB KRF Key of reference 

RAB KSZ Key size (bytes) 

RAB RAC Record access code 

RB$KEY Key access 

RAB ROP Record processing option mask 

RB$ASY Asynchronous operation 

RB$KGE Greater-than-or-equal key criterion 

RB$KGT Greater-than key criterion 



Table 5-22: FIND (Key Access) Output Fields 



Block Field Description 



RAB BKT Relative record number (RRN) 

RAB RFA Record file address 

RAB STS Completion status code 

RAB STV Completion status value 
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5.12 $FIND MACRO (RFA ACCESS) 

The $FIND macro calls the FIND operation routine to transfer a record 
(or part of a record) from a file to an I/O buffer. The FIND 
operation transfers the entire file if the file is relative or 
indexed, or if it has blocked records; it may transfer only part of 
the record if the record spans block boundaries. The FIND operation 
does not transfer the record to a user buffer. 

The target of an RFA-access FIND operation is the record having the 
record file address (RFA) you specify. 

FORMAT 

The format for the $FIND is: 

$FIND rabaddr [, [erraddr] [,sucaddr] ] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 

CONTROL BLOCKS 

You must supply a RAB for the FIND operation. 

OPTIONS 

Internal Stream Identifier 

The FIND operation reads the internal stream identifier from the 
1-word ISI field of the RAB. 

Asynchronous Operation 

If you want to execute the FIND operation asynchronously, set the 
RB$ASY mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the FIND operation executes synchronously. (Your program 
must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 

RFA Access 

Specify the RB$RFA code in the 1-byte RAC field of the RAB. 

RFA 

Specify the RFA for the record to be found in the 3-word RFA field of 
the RAB. 

STREAM CONTEXT 

The current-record context after an RFA access FIND operation is the 
found record (for an indexed file, in the context of the primary 
index); the next-record context is unchanged. If the FIND operation 
returns an error completion, the current-record context is undefined, 
and the next-record context is unchanged. 

5-54 



OPERATION MACRO DESCRIPTIONS 
$FIND MACRO (RFA ACCESS) 



RETURNED VALUES 



RRN 



For a relative file or for a sequential disk file with fixed-length 
records, the FIND operation returns the RRN of the found record in the 
2-word BKT field of the RAB. 

Completion Status and Value 

The FIND operation returns completion status in the 1-word STS field 
of the RAB and returns a completion value in the 1-word STV field of 
the RAB. Appendix A lists completion status symbols and values. 

CHECKLISTS 

Table 5-23 lists control block fields that are input to the FIND 
operation. Table 5-24 lists control block fields that are output by 
the FIND operation. 

Table 5-23: FIND (RFA Access) Input Fields 
Block Field Description 

RAB ISI Internal stream identifier 
RAB RAC Record access code 

RB$RFA RFA access 

RAB RFA Record file address 

RAB ROP Record processing option mask 

RB$ASY Asynchronous operation 



Table 5-24: FIND (RFA Access) Output Fields 
Block Field Description 



RAB BKT Relative record number (RRN) 
RAB STS Completion status code 
RAB STV Completion status value 
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5.13 $ FLUSH MACRO 

The $FLUSH macro calls the FLUSH operation routine to write any 
unwritten buffers for a stream. The FLUSH operation does not affect 
stream context, except that the current-record context is undefined 
for a following TRUNCATE or UPDATE operation. 

Note one special case: if a file was opened for deferred writing 
(FB$DFW set in the FOP field of the FAB for the CREATE or OPEN 
operation) , and was not opened for write sharing (FB$WRI cleared in 
the SH6 field of the FAB) , then a buffer may be controlled by a 
different stream, and it will not be written by the FLUSH operation. 

FORMAT 

The format for the $FLUSH is: 

$FLUSH rabaddr[ , [erraddr] [,sucaddr]] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 

CONTROL BLOCKS 

You must supply a RAB for the FLUSH operation. 

OPTIONS 

Internal Stream Identifier 

The FLUSH operation reads the internal stream identifier from the 
1-word ISI field of the RAB. 

Asynchronous Operation 

If you want to execute the FLUSH operation asynchronously, set the 
RB$ASY mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the FLUSH operation executes synchronously. (Your program 
must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 

STREAM CONTEXT 

The FLUSH operation does not affect stream context, except that the 
current-record context is undefined for a following TRUNCATE or UPDATE 
operation. 

RETURNED VALUES 

Completion Status and Value 

The FLUSH operation returns completion status in the 1-word STS field 
of the RAB and returns a completion value in the 1-word STV field of 
the RAB. Appendix A lists completion status symbols and values. 
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CHECKLISTS 

Table 5-25 lists control block fields that are input to the FLUSH 
operation. Table 5-26 lists control block fields that are output by 
the FLUSH operation. 

Table 5-25: FLUSH Input Fields 
Block Field Description 



RAB ISI Internal stream identifier 
RAB ROP Record processing option mask 

RB$ASY Asynchronous operation 



Table 5-26: FLUSH Output Fields 



Block Field Description 



RAB STS Completion status code 
RAB STV Completion status value 
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5.14 $FREE MACRO 

The $FREE macro calls the FREE operation routine to free a locked 

bucket for a stream. The FREE operation does not affect stream 

context, except that the current-record context is undefined for a 
following DELETE, TRUNCATE, or UPDATE operation. 

FORMAT 

The format for the $FREE is: 

$FREE rabaddr [ , [erraddr] [ ,sucaddr] ] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 



CONTROL BLOCKS 

You must supply a RAB for the FREE operation, 

OPTIONS 



Internal Stream Identifier 

The FREE operation reads the 
1-word ISI field of the RAB. 



internal stream identifier from the 



Asynchronous Operation 

If you want to execute the FREE operation asynchronously, set the 
RB$ASY mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the FREE operation executes synchronously. (Your program 
must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 

STREAM CONTEXT 

The FREE operation does not affect stream context, except that the 
current-record context is undefined for a following DELETE, TRUNCATE, 
or UPDATE operation. 



RETURNED VALUES 



Completion Status and Value 

The FREE operation returns completion status in the 1-word STS field 
of the RAB and returns a completion value in the 1-word STV field of 
the RAB. Appendix A lists completion status symbols and values. 

CHECKLISTS 

Table 5-27 lists control block fields that are input' to the FREE 
operation. Table 5-28 lists control block fields that are output by 
the FREE operation. 
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Table 5-27: FREE Input Fields 



Block Field Description 



RAB ISI Internal stream identifier 
RAB ROP Record processing option mask 







RB$ASY Asynchronous operation 


Table 5-28: FREE Output Fields 


Block 


Field 


Description 


RAB 
RAB 


STS 
STV 


Completion status code 
Completion status value 
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5.15 $GET MACRO (SEQUENTIAL ACCESS) 

The $GET macro calls the GET operation routine to transfer a record 
from a file to an I/O buffer and to a user buffer. 

The target of a sequential-access GET operation depends on whether the 
previous operation was a FIND operation: 

• If the previous operation was a successful FIND operation, the 
target of a sequential-access GET operation is the current 
record (or the first following record if the current record 
was deleted or its key changed in the interim) . 

• If the previous operation was not a successful FIND operation, 
the target of a sequential-access GET operation is the next 
record (for an indexed file, the next record under the current 
index) . 

FORMAT 

The format for the $GET is: 

$GET rabaddr [ , [erraddr] [ ,sucaddr] ] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 

CONTROL BLOCKS 

You must supply a RAB for the GET operation. 

OPTIONS 

Internal Stream Identifier 

The GET operation reads the internal stream identifier from the 1-word 
ISI field of the RAB. 

Asynchronous Operation 

If you want to execute the GET operation asynchronously, set the 
RB$ASY mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the GET operation executes synchronously. (Your program 
must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 

Sequential Access 

Specify the RB$SEQ code in the 1-byte RAC field of the RAB. 

User Buffer 

Specify a user buffer for the GET operation. The GET operation copies 
the retrieved record to this buffer if you do not specify locate mode 
(see next section, Locate Mode) ; the GET operation may copy the 
retrieved record to this buffer even if you specify locate mode. 
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Specify the address of the user buffer in the 1-word UBF field of the 
RAB, and specify the size (in bytes) of the user buffer in the 1-word 
USZ field of the RAB. 

If the file is in VFC record format, specify the address of a buffer 
for the fixed-length portion of the record in the 1-word RHB field of 
the RAB. 

Locate Mode 

If you want the GET operation to use locate mode (in which the record 

may not be transferred to the user buffer) , set the RB$LOC mask in the 

1-word ROP field of the RAB; if you do not set this mask, the record 
is transferred to the user buffer. 



STREAM CONTEXT 

The current-record context after a sequential access GET operation is 
the retrieved record; the next-record context is the record following 
the retrieved record. 

If the GET operation returns an error completion, the current-record 
context is undefined, and the next-record context is unchanged. 

RETURNED VALUES 



Record 

The GET operation returns the address and size of the retrieved record 
in the 1-word RBF field of the RAB, and the size (in bytes) of the 
record in the 1-word RSZ field of the RAB. 

If you did not specify locate mode for the GET operation, the record 
address returned in the RBF field is the address you specified in the 
UBF field; if you specified locate mode, the record address returned 
in the RBF field is either the address you specified in the UBF field, 
or the address of a location in an I/O buffer. 

If the file is in VFC format, the GET operation writes the 
fixed-length portion of the record in the buffer you specified in the 
RHB field of the RAB. 



RRN 

For a relative file or for a sequential disk file with fixed-length 
records, a sequential-access GET operation returns the relative record 
number (RRN) for the retrieved record in the 2-word BKT field of the 
RAB. 



RFA 

The GET operation returns the record file address (RFA) for the 
retrieved record in the 3-word RFA field of the RAB. 

i 
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Completion Status and Value 

The GET operation returns completion status in the 1-word STS field of 
the RAB and returns a completion value in the 1-word STV field of the 
RAB. Appendix A lists completion status symbols and values. 

CHECKLISTS 

Table 5-29 lists control block fields that are input to the GET 
operation. Table 5-30 lists control block fields that are output by 
the GET operation. 

Table 5-29: GET (Sequential Access) Input Fields 



Block Field Description 



RAB ISI Internal stream identifier 
RAB RAC Record access code 

RB$SEQ Sequential access 

RAB RHB VFC control buffer address 
RAB ROP Record processing option mask 

RB$ASY Asynchronous operation 
RB$LOC Locate mode 

RAB UBF User buffer address 

RAB USZ User buffer size (bytes) 



Table 5-30: GET (Sequential Access) Output Fields 



Block Field Description 



RAB BKT Relative record number (RRN) 

RAB RBF Record buffer address 

RAB RFA Record file address 

RAB RSZ Record size (bytes) 

RAB STS Completion status code 

RAB STV Completion status value 
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5.16 $GET MACRO (KEY ACCESS) 

The $GET macro calls the GET operation routine to transfer a record 
from a sequential disk file (with fixed-length records) , a relative 
file, or an indexed file to an I/O buffer and to a user buffer. 

The target of a key-access GET operation is the record having the 
specified key (under the specified match criterion) . For a relative 
file or for a sequential disk file with fixed-length records, the key 
is a relative record number (RRN) ; for an indexed file, the key is an 
index key under the specified index. 

FORMAT 

The format for the $GET is: 

$GET rabaddr [ , [erraddr] [ ,sucaddr] ] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 

CONTROL BLOCKS 

You must supply a RAB for the GET operation. 

OPTIONS 

Internal Stream Identifier 

The GET operation reads the internal stream identifier from the 1-word 
ISI field of the RAB. 

Asynchronous Operation 

If you want to execute the GET operation asynchronously, set the 
RB$ASY mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the GET operation executes synchronously. (Your program 
must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 

Key Access 

Specify the RB$KEY code in the 1-byte RAC field of the RAB. 

Key of Reference (Indexed File) 

Specify the key of reference in the 1-byte KRF field of the RAB. The 
key of reference is the reference number (REF field of KEY block) for 
the index you want to use for the GET operation. 

Key 

Specify a buffer containing the key for the record to be retrieved: 

specify the address of the key buffer in the 1-word KBF field of the 

RAB, and specify the size of the key in the 1-byte KSZ field of the 
RAB. 
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For a relative file or for a sequential file with fixed-length 
records, specify a 4-byte binary relative record number (RRN) as the 
key, and specify the key size as or 4. 

For an indexed file, specify a key of the same type as the key for the 
current index, and specify a key size no greater than the key size for 
the current index. For a nonstring key, the specified key size must 
be the key size defined for the index (or, equivalently, 0); for a 
string key, if you specify a key size smaller than the key size for 
the index, the GET operation searches for a record whose key begins 
with the specified partial key (under the specified key criterion) . 

Key Criterion 

Specify a key-criterion mask in the 1-word ROP field of the RAB. The 
symbols for key-criterion masks are: 

RB$KGE Greater-than-or-equal key criterion 
RB$KGT Greater-than key criterion 

If you specify the key-greater criterion, the GET operation searches 
for the first record whose key is greater than the key you specify; 
if you specify the key-greater-or-equal criterion, the GET operation 
searches for the first record whose key is greater than or equal to 
the key you specify; if you specify neither criterion, the GET 
operation searches for a record whose key exactly matches the key you 
specify. 

User Buffer 

Specify a user buffer for the GET operation. The GET operation copies 
the retrieved record to this buffer if you do not specify locate mode 
(see next section, Locate Mode); the GET operation may copy the 
retrieved record to this buffer even if you specify locate mode. 

Specify the address of the user buffer in the 1-word UBF field of the 
RAB, and specify the size (in bytes) of the user buffer in the 1-word 
USZ field of the RAB. 

If the file is in VFC record format, specify the address of a buffer 
for the fixed-length portion of the record in the 1-word RHB field of 
the RAB. 

Locate Mode 

If you want the GET operation to use locate mode (in which the record 
may not be transferred to the user buffer) , set the RB$L0C mask in the 
1-word ROP field of the RAB; if you do not set this mask, the record 
is transferred to the user buffer. 

STREAM CONTEXT 

The current-record context after a key access GET operation is the 
retrieved record; the next-record context is the record following the 
retrieved record. 

If the GET operation returns an error completion, the current-record 
context is undefined, and the next-record context is unchanged. 
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RETURNED VALUES 



Record 



The GET operation returns the address and size of the retrieved record 
in the 1-word RBF field of the RAB, and the size (in bytes) of the 
record in the 1-word RSZ field of the RAB. 

If you did not specify locate mode for the GET operation, the record 
address returned in the RBF field is the address you specified in the 
UBF field. If you specified locate mode, the record address returned 
in the RBF field is either the address you specified in the UBF field, 
or the address of a location in an I/O buffer. 

If the file is in VFC format, the GET operation writes the 
fixed-length portion of the record in the buffer you specified in the 
RHB field of the RAB. 



RRN 

For a relative file or for a sequential disk file with fixed-length 
records, a key-access GET operation returns the relative record number 
(RRN) for the retrieved record in the 2-word BKT field of the RAB. 

RFA 

The GET operation returns the record file address (RFA) for the 
retrieved record in the 3-word RFA field of the RAB. 

Completion Status and Value 

The GET operation returns completion status in the 1-word STS field of 
the RAB and returns a completion value in the 1-word STV field of the 
RAB. Appendix A lists completion status symbols and values. 

CHECKLISTS 

Table 5-31 lists control block fields that are input to the GET 
operation. Table 5-32 lists control block fields that are output by 
the GET operation. 
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Table 5-31: GET (Key Access) Input Fields 



Block Field Description 



RAB ISI Internal stream identifier 

RAB KBF Key buffer address 

RAB KRF Key of reference 

RAB KSZ Key size (bytes) 

RAB RAC Record access code 

RB$KEY Key access 

RAB RHB VFC control buffer address 
RAB ROP Record processing option mask 

RB$ASY Asynchronous operation 

RB$KGE Greater- than-or-equal key criterion 

RB$KGT Greater-than key criterion 

RB$LOC Locate mode 

RAB UBF User buffer address 

RAB USZ User buffer size (bytes) 



Table 5-32: GET (Key Access) Output Fields 



Block Field Description 



RAB BKT Relative record number (RRN) 

RAB RBF Record buffer address 

RAB RFA Record file address 

RAB RSZ Record size (bytes) 

RAB STS Completion status code 

RAB STV Completion status value 
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5.17 $GET MACRO (RFA ACCESS) 

The $GET macro calls the GET operation routine to transfer a record 
from a file to an I/O buffer and to a user buffer. 

The target of an RFA-access GET operation is the record having the 
record file address (RFA) you specify. 

FORMAT 

The format for the $GET is: 

$GET rabaddr [, [erraddr] [,sucaddr]] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 

CONTROL BLOCKS 

You must supply a RAB for the GET operation. 

OPTIONS 

Internal Stream Identifier 

The GET operation reads the internal stream identifier from the 1-word 
ISI field of the RAB. 

Asynchronous Operation 

If you want to execute the GET operation asynchronously, set the 
RB$ASY mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the GET operation executes synchronously. (Your program 
must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 

RFA Access 

Specify the RB$RFA code in the 1-byte RAC field of the RAB. 

RFA 

Specify the RFA for the record to be retrieved in the 3-word RFA field 
of the RAB. 

Oser Buffer 

Specify a user buffer for the GET operation. The GET operation copies 
the retrieved record to this buffer if you do not specify locate mode 
(see next section, Locate Mode) ; the GET operation may copy the 
retrieved record to this buffer even if you specify locate mode. 

Specify the address of the user buffer in the 1-word UBF field of the 
RAB, and specify the size (in bytes) of the user buffer in the 1-word 
USZ field of the RAB. 
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If the file is in VFC record format, specify the address of a buffer 
for the fixed-length portion of the record in the 1-word RHB field of 
the RAB. 



Locate Mode 

If you want the GET operation to use locate mode (in which the record 

may not be transferred to the user buffer) , set the RB$LOC mask in the 

1-word ROP field of the RAB; if you do not set this mask, the record 
is transferred to the user buffer. 

STREAM CONTEXT 

The current-record context after an RFA access GET operation is the 
retrieved record (for an indexed file, in the context of the primary 
index) ; the next-record context is the record following the retrieved 
record. If the GET operation returns an error completion, the 
current-record context is undefined, and the next- record context is 
unchanged. 

RETURNED VALUES 

Record 

The GET operation returns the address and size of the retrieved record 
in the 1-word RBF field of the RAB, and the size (in bytes) of the 
record in the 1-word RSZ field of the RAB. 

If you did not specify locate mode for the GET operation, the record 
address returned in the RBF field is the address you specified in the 
UBF field. If you specified locate mode, the record address returned 
in the RBF field is either the address you specified in the UBF field, 
or the address of a location in an I/O buffer. 

If the file is in VFC format, the GET operation writes the 
fixed-length portion of the record in the buffer you specified in the 
RHB field of the RAB. 

RRN 

For a relative file or for a sequential disk file with fixed-length 
records, an RFA-access GET operation returns the relative record 
number (RRN) for the retrieved record in the 2-word BKT field of the 
RAB. 

Completion Status and Value 

The GET operation returns completion status in the 1-word STS field of 
the RAB and returns a completion value in the 1-word STV field of the 
RAB. Appendix A lists completion status symbols and values. 

CHECKLISTS 

Table 5-33 lists control block fields that are input to the GET 
operation. Table 5-34 lists control block fields that are output by 
the GET operation. 
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Table 5-33: GET (RFA Access) Input Fields 



Block Field Description 



RAB ISI Internal stream identifier 
RAB RAC Record access code 

RB$RFA RFA access 

RAB RFA Record file address 

RAB RHB VFC control buffer address 

RAB ROP Record processing option mask 

RB$ASY Asynchronous operation 
RB$LOC Locate mode 

RAB UBF User buffer address 

RAB USZ User buffer size (bytes) 



Table 5-34: GET (RFA Access) Output Fields 



Block Field Description 



RAB BKT Relative record number (RRN) 

RAB RBF Record buffer address 

RAB RSZ Record size (bytes) 

RAB STS Completion status code 

RAB STV Completion status value 
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5.18 $NXTVOL MACRO 

The $NXTVOL macro calls the NXTVOL operation routine to advance the 
context for a stream to the beginning of the next magtape volume. 

FORMAT 

The format for the $NXTVOL is: 

$NXTVOL rabaddr[, [erraddr] [,sucaddr] ] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 

CONTROL BLOCKS 

You must supply a RAB for the NXTVOL operation. 

OPTIONS 

Internal Stream Identifier 

The NXTVOL operation reads the internal stream identifier from the 
1-word ISI field of the RAB. 

Asynchronous Operation 

If you want to execute the NXTVOL operation asynchronously, set the 
RB$ASY mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the NXTVOL operation executes synchronously. (Your program 
must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 

STREAM CONTEXT 

The NXTVOL operation destroys the current-record context; the 
next-record context after the NXTVOL operation is the first record of 
the new volume (or end-of-file, if there are no records on the new 
volume) . 

RETURNED VALUES 

Completion Status and Value 

The NXTVOL operation returns completion status in the 1-word STS field 
of the RAB and returns a completion value in the 1-word STV field of 
the RAB. Appendix A lists completion status symbols and values. 

CHECKLISTS 

Table 5-35 lists control block fields that are input to the NXTVOL 
operation. Table 5-36 lists control block fields that are output by 
the NXTVOL operation. 
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Table 5-35: NXTVOL Input Fields 



Block Field Description 



RAB ISI Internal stream identifier 
RAB ROP Record processing option mask 

RB$ASY Asynchronous operation 



Table 5-36: NXTVOL Output Fields 



Block Field Description 



RAB STS Completion status code 
RAB STV Completion status value 



5-71 



OPERATION MACRO DESCRIPTIONS 
$OPEN MACRO 



5.19 $OPEN MACRO 



The $OPEN macro calls the OPEN operation routine to open a file for 
processing by the calling task. 

FORMAT 

The format for the $OPEN is: 

$OPEN f abaddr [ , [erraddr] [ ,sucaddr] ] 

where fabaddr is the address of the FAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 

CONTROL BLOCKS 

You must supply a FAB for the OPEN operation. 

If you supply a NAM block and specify open by NAM block, the OPEN 
operation reads NAM block fields to obtain identifiers for the target 
file. 

To supply a NAM block for the OPEN operation, specify the address of 
the NAM block in the 1-word NAM field of the FAB. 

For each ALL block that you supply, the OPEN operation fills its 
fields with values describing the corresponding area (if any) of the 
file. You need not supply an ALL block for every area of the file. 
(If you are opening the file for block access, the OPEN operation 
writes information describing the file as a whole in the all block for 
area 0.) 

For each KEY block that you supply, the OPEN operation fills its 
fields with values describing the corresponding index (if any) for the 
file. You need not supply a KEY block for every index of the file. 
(If you are opening the file for block access, the OPEN operation does 
not write in KEY blocks.) 

If you supply a PRO block for a disk file, the OPEN operation fills 
its fields with values showing the owner and protection for the file. 

If you supply a DAT block for a disk file, the OPEN operation fills 
its fields with values showing the creation date, expiration date, 
revision date, and revision number for the file. 

If you supply a SUM block for a relative or indexed file, the OPEN 
operation fills its fields with values showing the number of areas and 
indexes for the file, and with its prologue version number. (If you 
are opening the file for block access, the OPEN operation returns the 
number of areas and number of keys as 0, and does not return the 
prologue version number.) 

This information is especially useful if you do not know how many 
areas or keys an indexed file has when you open it. If you supply a 
SUM block for the OPEN operation, you can get the number of areas and 
number of indexes from its fields, and then supply the correct number 
of ALL blocks and KEY blocks for the DISPLAY operation. 
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To supply XABs (ALL, DAT, KEY, PRO, and SUM blocks) for the OPEN 
operation, specify the address of the first XAB in the 1-word XAB 
field of the FAB; specify the address of the next XAB (if any) in the 
1-word NXT field of each XAB; specify in the NXT field of the last 
XAB. 

All KEY blocks must be together in the chain of XABs, and must be in 
ascending order (by the index reference number in the 1-byte REF field 
of the KEY block) ; the index reference numbers need not be 
consecutive. 

All ALL blocks must be together in the chain of XABs, and must be in 
ascending order (by the area identifier in the 1-byte AID field of the 
ALL block); the area identifiers need not be consecutive. 

Multiple DAT, PRO, or SUM XABs are illegal. 
OPTIONS 

File Specification (Nonwildcard OPEN Operation) 

The OPEN operation constructs the full file specification from the 
file string, the default string (which contributes only elements not 
present in the file string) , and RMS-11 defaults (which contribute 
elements not present in either the file string or the default string) . 

RMS-11 defaults are: 

• Device — The device to which the specified logical channel is 
assigned, or SY: if the specified logical channel is not 
assigned to any device. 

• Directory — The current directory for the task. 

• Name, type, version — Defaulted to null. 

The file string and the default string must not contain wildcards. 

Specify the address of the file string in the 1-word FNA field of the 
FAB. Specify the size (in bytes) of the file string in the 1-byte FNS 
field of the FAB; if you specify in the FNS field, the OPEN 
operation uses no file string. 

Specify the address of the default string in the 1-word DNA field of 

the FAB. Specify the size (in bytes) of the default string in the 

1-byte DNS field of the FAB; if you specify in the DNS field, the 

OPEN operation uses no default string. 

If you set the FB$FID mask in the 1-word FOP field of the FAB and 
supply a NAM block, the OPEN operation reads the device identifier 
from the 2-word DVI field of the NAM block; if this value is nonzero, 
the specified device overrides the device in the merged string. 

In the same circumstance, the OPEN operation reads the directory 
identifier from the 3-word DID field of the NAM block; if this value 
is nonzero, the specified directory overrides the directory in the 
merged string. 

In the same circumstance, the OPEN operation reads the file identifier 
from the 3-word FID field of the NAM block; if this value is zero, 
the specified file overrides any directory, name, type, and version 
elements previously obtained. 
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Open with Wildcard Context 

If you want to open a file that was found by a wildcard SEARCH 
operation (using the FAB and NAM block that the SEARCH operation 
used) , set the FB$FID mask in the 1-word FOP field of the FAB; this 
causes the OPEN operation to open the file without altering wildcard 
context. 

Expanded String Buffer 

If you want the OPEN operation to return the expanded string for the 
opened file, provide a buffer for the string. Specify the address of 
the expanded string buffer in the 1-word ESA field of the NAM block 
and its size (in bytes) in the 1-byte ESS field of the NAM block; if 
you specify in the ESS field, the OPEN operation does not return the 
expanded string. 

Key Name Buffer 

If you want the key name string for an index returned to a buffer, 
supply a KEY block for the index. Specify the index reference number 
in the 1-byte REF field of the KEY block, and specify the address of a 
32-byte buffer in the 1-word KNM field of the KEY block. If you do 
not supply a KEY block for an index, or if you specify in its KNM 
field, the OPEN operation does not return the key name string. 

While-Open Default Extension Sizes 

If you want to override the default extension size for the file while 
it is open, specify the while-open default file extension size (in 
blocks) in the 1-word DEQ field of the FAB. If you specify 0, the 
OPEN operation does not establish a while-open default extension size 
for the file; instead, it uses the permanent default extension size. 

The while-open default extension size for a file remains in force 
while the file is open, but does not change the file extension size 
established when the file was created. 

Private Buffer Pool 

If you want the OPEN operation to use a private buffer pool instead of 
the central buffer pool, specify the address of the (word-aligned) 
private buffer pool in the 1-word BPA field of the FAB, and its size 
(in bytes) in the 1-word BPS field of the FAB; this size must be a 
multiple of 4. 



If you specify in either the BPA field or the BPS 
operation uses the central buffer pool. 



field, the OPEN 



The pool that the OPEN operation uses is also used by the DISPLAY and 
EXTEND operations, and by stream and record or block operations while 
the file is open. 

Logical Channel 

Specify the logical channel for the OPEN operation in the 1-byte LCH 
field of the FAB. The logical channel number must not be the same as 
the logical channel number for any already-open file, and must not be 
0. 
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The logical channel that the OPEN operation uses is also used by the 
DISPLAY and EXTEND operations, and by stream and record or block 
operations while the file is open. 

Retrieval Pointers 

Specify the number of retrieval pointers for the open file in the 

1-byte RTV field of the FAB. If you specify 0, the OPEN operation 

uses the operating system default; if you specify -1, the OPEN 
operation maps as much of the file as possible. 

Requested-Access 

Specify one or more requested-access masks in the 1-byte FAC field of 
the FAB. This mask determines the access that the opening program has 
while the file is open. If you specify no requested-access mask, 
find/get access is allowed (the OPEN operation uses the mask FB$GET) . 
The symbols for requested-access masks are: 

FB$DEL Request find/get/delete access 

FB$GET Request find/get access 

FB$PUT Request put access 

FB$REA Request block read access 

FB$TRN Request find/get/truncate access 

FB$UPD Request find/get/update access 

FB$WRT Request block write access 

Note that FB$REA and FB$WRT override any record access requested. 

Access Sharing 

Specify the kinds of access that your program will share with other 
programs by setting an access-sharing mask in the 1-byte SHR field of 
the FAB. The symbols for access-sharing masks are: 

FB$GET Share find/get access 

FB$NIL No access sharing 

FB$UPI Share any access (user-provided interlock) 

FB$WRI Share find/get/put/update/delete access 

The kinds of access sharing are: 

• Shared read access 

Your program is willing to allow other programs to read the 
file, but not to write it. 

• Shared write access 

Your program is willing to allow other programs to both read 
and write the file. Shared write access is not allowed for a 
sequential file unless the file has undefined record format 
and your program opens the file for block access; shared 
write access is also not allowed for a relative or indexed 
file that your program opens for block access. In such cases, 
RMS-11 automatically converts the shared write access 
specification to a shared read access specification 
internally. 
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No shared access 



Your program is not willing to allow other programs to either 
read or write the file. RMS-11 does, however, allow other 
programs to read the file unless your program also requests 
some form of write access. 

• User-provided interlocking 

Your program and other cooperating programs define and enforce 
their own access interlocking; RMS-11 does not check access 
sharing. User-provided interlocking is allowed only for 
sequential disk files; otherwise, the FB$UPI mask is ignored 
(but other masks are honored) . 

Deferred Writing 

If you want deferred buffer writing for the open file, set the FB$DFW 
mask in the 1-word FOP field of the FAB; This means that RMS-11 does 
not necessarily write its buffers during a write-type operation 
(DELETE, PUT, or UPDATE) , but instead writes buffers only when it 
needs them for other operations (or when your program executes the 
FLUSH operation for the stream) . 

If you do not set the FB$DFW mask, the DELETE, PUT, and UPDATE 
operations write buffers to the file immediately. 

Note that record operations always use a form of deferred buffer 
writing for sequential files, and that block operations never use 
deferred buffer writing. Therefore you need only decide whether to 
use deferred writing for a record stream to a relative or indexed 
file. 

File Locking 

If you want the file to remain unlocked even if it is closed 

abnormally, set the FB$DLK mask in the 1-word FOP field of the FAB; 

if you do not set this mask, the operating system locks the file if it 
is closed abnormally. 

Magtape Beginning-of-File Positioning 

If you have requested some form of write access, and if you want a 
magtape file positioned to the beginning of the file when it is 
opened, set the FB$NEF mask in the 1-word FOP field of the FAB; if 
you do not set this mask, and if you requested some form of write 
access, the magtape is positioned to the end-of-file when the file is 
opened . 

Rewinding Magtape Before Open 

If you want a magtape rewound before a magtape file is opened, set the 
FB$RWO mask in the 1-word FOP field of the FAB; if you do not set 
this mask, the OPEN operation searches only from the current magtape 
position to the end of the magtape. 
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Rewinding Magtape on Close 

If you want the magtape rewound when the opened file is closed, set 
the FB$RWC mask in the 1-word FOP field of the FAB. If you do not set 
this mask, the magtape will not be rewound on close unless you set the 
FB$RWC mask for the CLOSE operation. Note, however, that if you set 
the FB$RWC mask for the OPEN operation, the magtape will be rewound 
even if you do not set the FB$RWC mask for the CLOSE operation. 

RETURNED VALUES 

Internal File Identifier 

The OPEN operation writes an internal file identifier in the 1-word 
IFI field of the FAB. (The CLOSE operation clears the internal file 
identifier .) 

The CLOSE, CONNECT, DISPLAY, and EXTEND operations read the internal 
file identifier; do not alter the IFI field while the file is open. 

Device Characteristics 

The OPEN operation returns device characteristics as masks in the 
1-byte DEV field of the FAB. The device characteristics are: 

• Printer or terminal (indicated by the set FB$CCL mask in the 
1-byte DEV field of the FAB and the set FB$REC mask in the 
1-byte DEV field of the FAB; for a terminal, the FB$TRM mask 
in the 1-byte DEV field of the FAB is also set) ; RMS-11 
treats a printer or terminal as a unit-record device. 

• Disk, DECtape, or DECTAPE II (indicated by the set FB$MDI mask 
in the 1-byte DEV field of the FAB); RMS-11 treats a disk, 
DECtape, or DECTAPE II as a disk device. 

• Unit-record device (indicated by the set FB$REC mask in the 
1-byte DEV field of the FAB) . 

• Non-ANSI magtape or cassette tape (indicated by the set FB$SDI 
mask in the 1-byte DEV field of the FAB and the set FB$REC 
mask in the 1-byte DEV field of the FAB) ; RMS-11 treats a 
non-ANSI magtape or a cassette tape as a unit-record device. 

• ANSI-format magtape (indicated by the set FB$SQD mask in the 
1-byte DEV field of the FAB) . 

Device, Directory, and File Identifiers 

If you supply a NAM block, the OPEN operation writes a device 
identifier in the 2-word DVI field of the NAM block, a directory 
identifier in the 3-word DID field of the NAM block (unless directory 
processing was bypassed due to use of the file identifier on input) , 
and a file identifier in the 3-word FID field of the NAM block. 

Expanded String 

If you specify a buffer for the expanded string for the file (ESA and 
ESS fields in the NAM block) , the OPEN operation writes the expanded 
string for the opened file in this buffer, and writes the length (in 
bytes) of the string in the 1-byte ESL field of the NAM block. 
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File Allocation, Bucket Size, and Contiguity 

The OPEN operation writes the file allocation size (in blocks) in the 
2-word ALQ field of the FAB, and the file bucket size or largest area 
bucket size (in blocks) in the 1-byte BKS field of the FAB. If the 
file is contiguous, the OPEN operation sets the FB$CTG mask in the 
1-word FOP field of the FAB. 

Extension size 

The OPEN operation writes the current default extension size for the 
open file in the 1-word DEQ field of the FAB. 

File Organization 

The OPEN operation writes the file organization code in the 1-byte ORG 
field of the FAB. The symbols for file organization codes are: 

FB$IDX Indexed file organization 
FB$REL Relative file organization 
FB$SEQ Sequential file organization 

Record Format 

The OPEN operation writes the record format code in the 1-byte RFM 
field of the FAB. The symbols for record format codes are: 

FB$FIX Fixed-length record format 

FB$STM Stream record format 

FB$UDF Undefined record format 

FB$VAR Variable-length record format 

FB$VFC VFC record format 

If the record format is VFC, the OPEN operation writes the size (in 
bytes) of the VFC header field in the 1-byte FSZ field of the FAB; 
otherwise it writes in the FSZ field. 

Blocked Records (Sequential Disk File) 

If the file was created specifying blocked records, the OPEN operation 
sets the FB$BLK mask in the 1-byte RAT field of the FAB. (The OPEN 
operation sets the mask if it was set when the file was created, even 
if the file is not a sequential file; preservation of this mask 
allows you to copy a sequential file to a file of a different 
organization and back without losing the blocked-record 
characteristic . ) 

Record-Output Handling 

The OPEN operation writes the record-output mask in the 1-byte RAT 
field of the FAB. The symbols for record-output masks are: 

FB$CR Add CRLF to print record (LF-record-CR) 

FB$FTN FORTRAN-style carriage-control character in record 

FB$PRN VFC print record handling 
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Record Size 

The OPEN operation writes the maximum permitted record size (in bytes) 
in the 1-word MRS field of the FAB. 

Maximum Record Number 

If the file is a relative file (FB$REL in the ORG field), the OPEN 
operation writes the maximum record number in the 2-word MRN field of 
the FAB (unless you are opening the file for block access) . 



Magtape Block Size 

For a magtape file, the OPEN operation writes 
characters) in the 1-word BLS field of the FAB. 



the block size (in 



Longest Record Length 

The OPEN operation writes the length of the longest record in the file 
in the 1-word LRL field of the FAB; this value is meaningful only for 
sequential files. 



Area Descriptions 



For each ALL block that you supply, the OPEN operation writes a 
description in its fields of the corresponding area of the file 
(unless you are opening the file for block access) . Area is 
described in the ALL block containing in its AID field, area 1 is 
described in the ALL block containing 1 in its AID field, and so 
forth. 

The OPEN operation writes three sizes for a file area: the size (in 
blocks) of the unused portion of the area in the 2-word ALQ field of 
the ALL block, the default area extension size (in blocks) in the 
1-word DEQ field of the ALL block, and the area bucket size (in 
blocks) in the 1-byte BKZ field of the ALL block. (If you are opening 
the file for block access, only the ALL block for area is written, 
and the ALL block contains the current file allocation size, default 
file extension size, and file bucket size.) 

The OPEN operation clears the 1-byte ALN field of the ALL block and 
the XB$HRD mask in the 1-byte AOP field of the ALL block. If you are 
opening a sequential or relative file for any access, or an indexed 
file for block access, the OPEN operation sets the XB$CTG mask in the 
1-byte AOP field of the ALL block if the file is contiguous; 
otherwise it clears the entire 1-byte AOP field of the ALL block. 



Key Descriptions 

For each KEY block that you supply, the OPEN operation writes a 
description in its fields of the corresponding index of the file. 
(The OPEN operation does not write in KEY blocks if you are opening 
the file for block access.) 

The primary index is described in the KEY block containing in its 
REF field, the first alternate index is described in the KEY block 
containing 1 in its REF field, and so forth. 
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The OPEN operation writes the key data type code in the 1-byte DTP 
field of the KEY block. The symbols for key data type codes are: 

XB$BN2 16-bit unsigned integer 

XB$BN4 32-bit unsigned integer 

XB$IN2 15-bit signed integer 

XB$IN4 31-bit signed integer 

XB$PAC Packed decimal number 

XB$STG String 

The OPEN operation writes the sizes of key segments in the 8-byte SIZ 
field of the KEY block. The size (in bytes) of the first key segment 
is in the first byte of the SIZ field, the size of the second segment 
is in the second byte of the SIZ field, and so forth. If the key has 
fewer than eight segments, the first byte containing establishes the 
number of key segments. 

The OPEN operation writes the positions of key segments in the 8-word 
POS field of the KEY block. The position (leftmost position is 0) of 
the first key segment is in the first word of the POS field, the 
position of the second segment is in the second word of the POS field, 
and so forth. If the key has fewer than eight segments, the remaining 
words of the POS field contain unpredictable values. 

The OPEN operation writes a key flags mask in the 1-byte FLG field of 
the KEY block. The symbols for key flags masks are: 

XB$CHG Record key changes allowed on update 

XB$DUP Duplicate record keys allowed 

XB$INI No entries yet made in index 

XB$NUL Null record keys not indexed 

The OPEN operation writes the null-key character in the 1-byte NUL 

field of the KEY block; this character is meaningful only if the 

XB$NUL mask in the FLG field is set and if the key is a string key 

(XB$STG in the DTP field) . " 

The OPEN operation writes area numbers for the index: the area for 
the data level in the 1-byte DAN field of the KEY block, the area for 
the lowest index level in the 1-byte LAN field of the KEY block, and 
the area for higher index levels in the 1-byte IAN field of the KEY 
block. 

The OPEN operation writes bucket fill numbers for the index areas: 
the fill number for the data area in the 1-word DFL field of the KEY 
block, and the fill number for the index areas in the 1-word IFL field 
of the KEY block. 

The OPEN operation writes bucket sizes for index areas: the data area 
bucket' size (in blocks) in the 1-byte DBS field of the KEY block, and 
the index area bucket size (in blocks) in the 1-byte IBS field of the 
KEY block. 

The OPEN operation writes virtual block numbers for the index areas: 

the virtual block number for the first data bucket in the 2-word DVB 

field of the KEY block, and the virtual block number of the root index 
bucket in the 2-word RVB field of the KEY block. 

The OPEN operation writes the number of levels in the index (not 
including the data level) in the 1-byte LVL field of the KEY block. 

The OPEN operation writes the minimum size (in bytes) of a record that 
contains the key for the index in the 1-word MRL field of the KEY 
block. 
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The OPEN operation writes key segment information for the index: the 
number of key segments in the 1-byte NSG field of the KEY block, and 
the total key size (sum of segments, in bytes) in the 1-byte TKS field 
of the KEY block. 

File Owner and Protection (Disk File) 

If the file is a disk file, and if you supply a PRO block, the OPEN 
operation writes the project (or group) portion of the file owner code 
in the 1-word PRJ field of the PRO block, the programmer (or member) 
portion of the file owner code in the 1-word PRG field of the PRO 
block, and the file protection code in the 1-word PRO field of the PRO 
block. 

File Dates 

If you supply a DAT block for a disk file, the OPEN operation writes 
four values in its fields: the creation date in the 4-word CDT field 
of the DAT block, the expiration date in the 4-word EDT field of the 
DAT block, the revision date in the 4-word RDT field of the DAT block, 
and the revision number (number of times the file has been opened for 
write access and then closed) in the 1-word RVN field of the DAT 
block . 

File Summary Information 

If you supply a SUM block and are opening an indexed file, the OPEN 
operation writes three values in its fields: the number of file areas 
in the 1-byte NOA field of the SUM block, the number of file indexes 
in the 1-byte NOK field of the SUM block, and the prologue version 
number (for a relative or indexed file) in the 1-word PVN field of the 
SUM block. (If you are opening the file for block access, the OPEN 
operation returns the number of areas and the number of keys as 0, and 
does not return the prologue version number.) 



File Specification Characteristics 



The OPEN operation sets masks in the 1-word FNB field of the NAM block 
to show which file specification elements were present. in the file 
string and default string. These masks and their meanings are: 



NB$NOD Node in file string or 

NB$DEV Device in file string 

NB$DIR Directory in file stri 

NB$QUO Quoted string in file 

NB$NAM File name in file stri 

NB$TYP File type in file stri 

NB$VER File version in file s 

NB$WDI Wildcard directory in 

NB$WNA Wildcard file name in 

NB$WTY Wildcard file type in 

NB$WVE Wildcard file version 



default string 
or default string 
ng or default string 
string or default string 
ng or default string 
ng or default string 
tring or default string 
file string or default string 
file string or default string 
file string or default string 
in file string or default string 



Wildcard Context Information 

If you cleared the FB$FID mask, the OPEN operation clears the NB$WCH 
mask in the 1-word FNB field of the NAM block and the 1-byte RSL field 
of the NAM block; this shows that no wildcard context information 
exists after the operation and that no resultant string was returned. 
If you set the FB$FID mask, the OPEN operation does not alter the 



5-81 



OPERATION MACRO DESCRIPTIONS 
$OPEN MACRO 



NB$WCH 
field. 



mask, and (if the NB$WCH mask is set) does not alter the RSL 



Completion Status and Value 

The OPEN operation returns completion status in the 1-word STS field 
of the FAB and returns a completion value in the 1-word STV field of 
the FAB. Appendix A lists completion status symbols and values. 

CHECKLISTS 

Table 5-37 lists control block fields that are input to the OPEN 
operation. Table 5-38 lists control block fields that are output by 
the OPEN operation. 



Table 5-37: OPEN Input Fields 



Block Field Description 



ALL 
ALL 
DAT 
FAB 
FAB 
FAB 
FAB 
FAB 
FAB 



AID 
NXT 
NXT 
BPA 
BPS 
DEQ 
DNA 
DNS 
FAC 



FAB FNA 
FAB FNS 
FAB FOP 



FAB 
FAB 
FAB 
FAB 



LCH 
NAM 
RTV 
SHR 



Area number 

Next XAB address 

Next XAB address 

Private buffer pool address 

Private buffer pool size (bytes) 

While-open file default extension size (blocks) 

Default string address 

Default string size (bytes) 

Requested access mask 

FB$DEL Request find/get/delete access 

FB$GET Request find/get access 

FB$PUT Request put access 

FB$REA Request block read access 

FB$TRN Request find/get/truncate access 

FB$UPD Request find/get/update access 

FB$WRT Request block write access 

File string address 
File string size (bytes) 
File processing option mask 

FB$DFW Defer writing 

FB$DLK No file locking on abnormal close 

FB$FID Use information in NAM block 

FB$NEF No end-of-file magtape positioning 

FB$RWC Rewind magtape after closing file 

FB$RWO Rewind magtape before searching for file 

Logical channel number 
NAM block address 
Retrieval pointer count 
Shared access mask 



FB$GET Share find/get access 

FB$NIL No access sharing 

FB$UPI Share any access (user-provided interlock) 

FB$WRI Share find/get/put/update/delete access 



(Continued on next page) 
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Table 5-37 (Cont.): OPEN Input Fields 



Block Field Description 



FAB 


XAB 


KEY 


KNM 


KEY 


NXT 


KEY 


REF 


NAM 


DID 


NAM 


DVI 


NAM 


ESA 


NAM 


ESS 


NAM 


FID 


NAM 


FNB 



PRO 
SUM 



NXT 
NXT 



XAB address 

Key name buffer address 

Next XAB address 

Index reference number 

Directory identifier 

Device identifier 

Expanded string buffer address 

Expanded string buffer size (bytes) 

File identifier 

File specification mask 

NB$WCH Wildcard context established 

Next XAB address 
Next XAB address 



Table 5-38: OPEN Output Fields 



Block Field Description 



ALL ALN 
ALL ALQ 
ALL AOP 



ALL 
ALL 
DAT 
DAT 
DAT 
DAT 
FAB 
FAB 
FAB 
FAB 
FAB 



BKZ 
DEQ 
CDT 
EDT 
RDT 
RVN 
ALQ 
BKS 
BLS 
DEQ 
DEV 



FAB 



FOP 



FAB 


FSZ 


FAB 


IFI 


FAB 


LRL 



Area alignment mask 

Unused area allocation size (blocks) 

Area option mask 

XB$CTG Contiguous area 

XB$HRD Hard area location (cleared) 

Area bucket size (blocks) 

Area default extension size (blocks) 

File creation date 

File expiration date 

File revision date 

File revision number 

Current file allocation (blocks) 

File bucket size (blocks) 

Magtape block size (characters) 

Current file default extension size (blocks) 

Device characteristic mask 

FB$CCL Carriage-control device 

FB$MDI Multidirectory device 

FB$REC Record-oriented device 

FB$SDI Single-directory device 

FB$SQD Sequential device 

FB$TRM Terminal device 

File processing option mask 

FB$CTG Contiguous file 

Fixed control area size for VFC records (bytes) 
Internal file identifier 
Longest record length 



(Continued on next page) 
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Table 5-38 (Cont.) : OPEN Output Fields 



Block Field Description 



FAB MRN Maximum record number 

FAB MRS Maximum record size (bytes) 

FAB ORG File organization code 

FB$SEQ Sequential file organization 
FB$REL Relative file organization 
FB$IDX Indexed file organization 

FAB RAT Record handling mask 

FB$BLK Blocked records 

FB$CR Add CRLF to print record (LF-record-CR) 

FB$FTN FORTRAN-style carriage-control character in 

record 
FB$PRN VFC print record handling 

FAB RFM Record format code 

FB$UDF Undefined record format 

FB$FIX Fixed-length record format 

FB$VAR Variable-length record format 

FB$VFC VFC record format 

FB$STM Stream record format 

FAB STS Completion status code 

FAB STV Completion status value 

KEY DAN Data area number 

KEY DBS Data area bucket size (blocks) 

KEY DFL Data bucket fill factor 

KEY DTP Key data type code 

XB$BN2 16-bit unsigned integer 

XB$BN4 32-bit unsigned integer 

XB$IN2 15-bit signed integer 

XB$IN4 31-bit signed integer 

XB$PAC Packed decimal number 

XB$STG String 

KEY DVB First data bucket virtual block number 
KEY FLG Index option mask 

XB$CHG Record key changes allowed on update 

XB$DUP Duplicate record keys allowed 

XB$INI No entries yet made in index 

XB$NUL Null record keys not indexed 

Higher level index area number 

Index area bucket size (blocks) 

Index bucket fill factor 

Lowest index level area number 

Number of index levels (not including data level) 

Minimum length of record containing key (bytes) 

Key segment count 

Null key character 

Key segment positions 

(Continued on next page) 
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IAN 


KEY 


IBS 


KEY 


IFL 


KEY 


LAN 


KEY 


LVL 


KEY 


MRL 


KEY 


NSG 


KEY 


NUL 


KEY 


POS 
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Table 5-38 (Cont.) : OPEN Output Fields 



Block Field Description 



KEY RVB Root index bucket virtual block number 

KEY SIZ Key segment sizes (bytes) 

KEY TKS Total key size (sum of key segment sizes) (bytes) 

NAM DID Directory identifier 

NAM DVI Device identifier 

NAM ESL Expanded string length (bytes) 

NAM FID File identifier 

NAM FNB File specification mask 

NB$NOD Node in file string or default string 
NB$DEV Device in file string or default string 
NB$DIR Directory in file string or default string 
NB$QUO Quoted string in file string or default 

string 
NB$NAM File name in file string or default string 
NB$TYP File type in file string or default string 
NB$VER File version in file string or default 

string 
NB$WDI Wildcard directory in file string or 

default string 
NB$WNA Wildcard file name in file string or 

default string 
NB$WTY Wildcard file type in file string or 

default string 
NB$WVE Wildcard file version in file string or 

default string 
NB$WCH Wildcard context established 

NAM RSL Resultant string length (bytes) (cleared) 

PRO PRG Programmer or member portion of file owner code 

PRO PRJ Project or group portion of file owner code 

PRO PRO File protection code 

SUM NOA Number of areas 

SUM NOK Number of indexes 

SUM PVN Prologue version number 
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5.20 $PARSE MACRO 

The $PARSE macro calls the PARSE operation routine to analyze a file 
specification. 

FORMAT 

The format for the $PARSE is: 

SPARSE fabaddr [, [erraddr] [,sucaddr] ] 

where fabaddr is the address of the FAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 

CONTROL BLOCKS 

You must supply a FAB for the PARSE operation. 

If you supply a NAM block for the PARSE operation, the operation 
routine writes file information in its fields. This information is 
suitable as input to subsequent wildcard SEARCH operations. 

To supply a NAM block for the PARSE operation, specify the address of 
the NAM block in the 1-word NAM field of the FAB. 

To supply XABs (ALL, DAT, KEY, PRO, and SUM blocks) for the PARSE 
operation, specify the address of the first XAB in the 1-word XAB 
field of the FAB; specify the address of the next XAB (if any) in the 
1-word NXT field of each XAB; specify in the NXT field of the last 
XAB. 

All KEY blocks must be together in the chain of XABs, and must be in 
ascending order (by the index reference number in the 1-byte REF field 
of the KEY block) ; the index reference numbers need not be 
consecutive. 

All ALL blocks must be together in the chain of XABs, and must be in 
ascending order (by the area identifier in the 1-byte AID field of the 
ALL block); the area identifiers need not be consecutive. 

Multiple DAT, PRO, or SUM XABs are illegal. 
OPTIONS 

File Specification 

The PARSE operation constructs the full file specification from the 
file string, the default string (which contributes only elements not 
present in the file string), and RMS-11 defaults (which contribute 
elements not present in either the file string or the default string) . 



5-86 



OPERATION MACRO DESCRIPTIONS 
$ PARSE MACRO 



RMS-11 defaults are: 

Device — The device to which the specified logical channel is 
assigned, or SY: if the specified logical channel is not 
assigned to any device. 

• Directory — The current directory for the task. 

• Name, type, version — Defaulted to null. 

Specify the address of the file string in the 1-word FNA field of the 
FAB. Specify the size (in bytes) of the file string in the 1-byte FNS 
field of the FAB; if you specify in the FNS field, the PARSE 
operation uses no file string. 

Specify the address of the default string in the 1-word DNA field of 
the FAB. Specify the size (in bytes) of the default string in the 
1-byte DNS field of the FAB; if you specify in the DNS field, the 
PARSE operation uses no default string. 

Expanded String Buffer 

If you want the PARSE operation to return the expanded string for the 
file, provide a buffer for the string. If you want subsequent 
wildcard SEARCH operations to use the results of the PARSE operation, 
you must provide an expanded string buffer. 

Specify the address of the expanded string buffer in the 1-word ESA 
field of the NAM block. Specify the size (in bytes) of the expanded 
string buffer in the 1-byte ESS field of the NAM block; if you 
specify in the ESS field, the PARSE operation does not return the 
expanded string. 

Private Buffer Pool 

If you want the PARSE operation to use a private buffer pool instead 

of the central buffer pool, specify the address of the (word-aligned) 

private buffer pool in the 1-word BPA field of the FAB, and its size 

(in bytes) in the 1-word BPS field of the FAB; this size must be a 
multiple of 4. 

If you specify in either the BPA field or the BPS field, the PARSE 
operation uses the central buffer pool. 

Logical Channel 

Specify the logical channel for the PARSE operation in the 1-byte LCH 

field of the FAB. The logical channel number must not be the same as 

the logical channel number for any already-open file, and must not be 
0. 

RETURNED VALUES 

Wildcard Initialization 

If you supplied a NAM block to be initialized for wildcard SEARCH 
operations, the PARSE operation clears several fields: the 3-word DID 
field of the NAM block, the 1-byte RSL field of the NAM block, the 
1-word WCC field of the NAM block, and the 1-word WDI field of the NAM 
block. These cleared fields are part of the initialization for 
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subsequent wildcard SEARCH operations. 

The PARSE operation writes a match-pattern (for subsequent wildcard 
SEARCH operations) in the expanded string buffer, and writes the 
length (in bytes) of the expanded string in the 1-byte ESL field of 
the NAM block. 

The PARSE operation sets the NB$WCH mask in the 1-word FNB field of 
the NAM block, showing that wildcard information in the NAM block is 
initialized. 

Device Characteristics 

The PARSE operation returns device characteristics as masks in the 
1-byte DEV field of the FAB. The device characteristics are: 

• Printer or terminal (indicated by the set FB$CCL mask in the 
1-byte DEV field of the FAB and the set FB$REC mask in the 
1-byte DEV field of the FAB; for a terminal, the FB$TRM mask 
in the 1-byte DEV field of the FAB is also set); RMS-11 
treats a printer or terminal as a unit-record device. 

• Disk, DECtape, or DECTAPE II (indicated by the set FB$MDI mask 
in the 1-byte DEV field of the FAB); RMS-11 treats a disk, 
DECtape, or DECTAPE II as a disk device. 

• Unit-record device (indicated by the set FB$REC mask in the 
1-byte DEV field of the FAB) . 

• Non-ANSI magtape or cassette tape (indicated by the set FB$SDI 
mask in the 1-byte DEV field of the FAB and the set FB$REC 
mask in the 1-byte DEV field of the FAB) ; RMS-11 treats a 
non-ANSI magtape or a cassette tape as a unit-record device. 

• ANSI-format magtape (indicated by the set FB$SQD mask in the 
1-byte DEV field of the FAB) . 

Device Identifier 

If you supply a NAM block, the PARSE operation writes a device 
identifier in the 2-word DVI field of the NAM block. 

File Specification Characteristics 

The PARSE operation sets masks in the 1-word FNB field of the NAM 
block to show which file specification elements were present in the 
file string and default string. These masks and their meanings are: 

NB$NOD Node in file string or default string 

NB$DEV Device in file string or default string 

NB$DIR Directory in file string or default string 

NB$QUO Quoted string in file string or default string 

NB$NAM File name in file string or default string 

NB$TYP File type in file string or default string 

NB$VER File version in file string or default string 

NB$WDI Wildcard directory in file string or default string 

NB$WNA Wildcard file name in file string or default string 

NB$WTY Wildcard file type in file string or default string 

NB$WVE Wildcard file version in file string or default string 
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Expanded String 

If you supply a NAM block, and if the input file specification string 
does not contain wildcard characters, the PARSE operation writes the 
expanded string in the expanded string buffer; this string is a fully 
qualified file specification except that the file version number (if 
any) from the input file specification is unchanged. 

Completion Status and Value 

The PARSE operation returns completion status in the 1-word STS field 
of the FAB and returns a completion value in the 1-word STV field of 
the FAB. Appendix A lists completion status symbols and values. 

CHECKLISTS 

Table 5-39 lists control block fields that are input to the PARSE 
operation. Table 5-40 lists control block fields that are output by 
the PARSE operation. 



Table 5-39: PARSE Input Fields 



Block Field Description 



ALL 


NXT 


DAT 


NXT 


FAB 


BPA 


FAB 


BPS 


FAB 


DNA 


FAB 


DNS 


FAB 


FNA 


FAB 


FNS 


FAB 


LCH 


FAB 


NAM 


KEY 


NXT 


NAM 


ESA 


NAM 


ESS 


PRO 


NXT 


SUM 


NXT 



Next XAB address 

Next XAB address 

Private buffer pool address 

Private buffer pool size (bytes) 

Default string address 

Default string size (bytes) 

File string address 

File string size (bytes) 

Logical channel number 

NAM block address 

Next XAB address 

Expanded string buffer address 

Expanded string buffer size (bytes) 

Next XAB address 

Next XAB address 



Table 5-40: PARSE Output Fields 



Block Field Description 



FAB DEV Device characteristic mask 

FB$CCL Carriage-control device 

FB$MDI Multidirectory device 

FB$REC Record-oriented device 

FB$SDI Single-directory device 

FB$SQD Sequential device 

FB$TRM Terminal device 

FAB STS Completion status code 

FAB STV Completion status value 

NAM DID Directory identifier (cleared) 

NAM DVI Device identifier 

NAM ESL Expanded string length (bytes) 



(Continued on next page) 
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Table 5-40 (Cont.): PARSE Output Fields 



Block Field Description 



NAM 



FNB 



NAM RSL 
NAM WCC 
NAM WD I 



File specification mask 

NB$NOD Node in file string or default string 
NB$DEV Device in file string or default string 
NB$DIR Directory in file string or default string 
NB$QUO Quoted string in file string or default 

string 
NB$NAM File name in file string or default string 
NB$TYP File type in file string or default string 
NB$VER File version in file string or default 

string 
NB$WCH Wildcard context established 
NB$WDI Wildcard directory in file string or 

default string 
NB$WNA Wildcard file name in file string or 

default string 
NB$WTY Wildcard file type in file string or 

default string 
NB$WVE Wildcard file version in file string or 

default string 

Resultant string length (bytes) (cleared) 

Wildcard context (cleared) 

Wildcard directory context (cleared) 
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5.21 $POT MACRO (SEQUENTIAL ACCESS) 

The $PUT macro calls the PUT operation routine to transfer a record 
from a user buffer to an I/O buffer and to a file. 

The target of a sequential-access PUT operation depends on the file 
organization: 

• For a sequential file, the target of a sequential-access PUT 
operation is the end-of-file, and the next-record context must 
be the end-of-file. 

• For a relative file, the target of a sequential-access PUT 
operation is the next cell (as determined by the next-record 
context or by the context of an immediately preceding 
sequential access PUT operation) . 

• For an indexed file, a sequential-access PUT operation has no 
target; the PUT operation inserts the record and updates 
indexes. If the immediately preceding operation was also a 
sequential access PUT operation, the primary key value in your 
record must be greater than or equal to the primary key value 
of the preceding record. 

FORMAT 

The format for the $PUT is: 

$PUT rabaddr [ , [erraddr] [ ,sucaddr] ] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 

CONTROL BLOCKS 

You must supply a RAB for the PUT operation. 

OPTIONS 

Internal Stream Identifier 

The PUT operation reads the internal stream identifier from the 1-word 
ISI field of the RAB. 

Asynchronous Operation 

If you want to execute the PUT operation asynchronously, set the 
RB$ASY mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the PUT operation executes synchronously. (Your program 
must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 

Sequential Access 

Specify the RB$SEQ code in the 1-byte RAC field of the RAB. 
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Record 



Specify the address of the record to be transferred in the 1-word RBF 
field of the RAB, and the size (in bytes) of the record in the 1-word 
RSZ field of the RAB. 

If the record is in VFC format, specify the address of the 
fixed-length portion of the record in the 1-word RHB field of the RAB. 
If you specify in this field, the record header will be null-filled. 

Locate Mode 

For a sequential file, if you want the PUT operation to use locate 
mode, specify the address of the user buffer in the 1-word UBF field 
of the RAB, specify the maximum size of the record for the next PUT 
operation in the 1-word USZ field of the RAB, and set the RB$LOC mask 
in the 1-word ROP field of the RAB. 

The PUT operation returns (in the RBF field) the address of a location 
where your program can build the next record for output. The maximum 
next record size that you specify in the USZ field determines whether 
the next record can fit into an I/O buffer. 

Bucket Fill Number Honoring 

If you want the PUT operation to honor bucket fill numbers for the 
file and its areas, set the RB$LOA mask in the 1-word ROP field of the 
RAB. If you do not set this mask, the PUT operation fills buckets 
without regard to bucket fill numbers. 

Update Existing Record (Relative File) 

If you want to transfer the record to a cell in a relative file even 

if the cell contains a record, set the RB$UIF mask in the 1-word ROP 

field of the RAB. If you do not set this mask, and if the cell 

already contains a record, the PUT operation returns an error 
completion and does not transfer the record. 

Mass Insertion (Indexed File) 

For an indexed file, using mass- insertion mode for a series of PUT 
operations speeds up the insertion of a series of records. To use 
mass-insertion mode for a series of records, set the RB$MAS mask in 
the 1-word ROP field of the RAB for each PUT operation in the series. 

STREAM CONTEXT 

The current-record and next-record contexts after a sequential access 
PUT operation are undefined. 
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RETURNED VALUES 



Next Record Buffer 



If you specified locate mode for the PUT operation, the PUT operation 
returns the address of a location where your program can build the 
next record for output in the 1-word RBF field of the RAB. This 
address gives a location in the I/O buffer (if there is room for 
another record there) , or the location of your user buffer (if not) . 



RRN 



For a relative file or for a sequential disk file with fixed-length 

records, a sequential-access PUT operation returns the relative record 

number (RRN) for the inserted record in the 2-word BKT field of the 
RAB. 



RFA 

The PUT operation returns the record file address (RFA) for the 
inserted record in the 3-word RFA field of the RAB. 

Completion Status and Value 

The PUT operation returns completion status in the 1-word STS field of 
the RAB and returns a completion value in the 1-word STV field of the 
RAB. Appendix A lists completion status symbols and values. 

CHECKLISTS 

Table 5-41 lists control block fields that are input to the PUT 
operation. Table 5-42 lists control block fields that are output by 
the PUT operation. 

Table 5-41: PUT (Sequential Access) Input Fields 



Block Field Description 



RAB ISI Internal stream identifier 
RAB RAC Record access code 

RB$SEQ Sequential access 

RAB RBF Record buffer address 

RAB RHB VFC control buffer address 

RAB ROP Record processing option mask 

RB$ASY Asynchronous operation 

RB$LOA Honor bucket fill numbers 

RB$LOC Locate mode 

RB$MAS Mass insert 

RB$UIF Update if record exists 

RAB RSZ Record size (bytes) 
RAB UBF User buffer address 
RAB USZ User buffer size (bytes) 
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Table 5-42: POT (Sequential Access) Output Fields 



Block Field Description 



RAB BKT Relative record number (RRN) 

RAB RFA Record file address 

RAB RBF Record buffer address 

RAB STS Completion status code 

RAB STV Completion status value 
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5.22 $PUT MACRO (KEY ACCESS) 



The $PUT macro calls the PUT operation routine to transfer a record 
from a user buffer to an I/O buffer and to a sequential disk file 
(with fixed-length records), a relative file, or an indexed file. 

The target of a key-access POT operation depends on the file 
organization: 

• For a sequential disk file (with fixed-length records) or a 
relative file, the key is a relative record number (RRN) , and 
the target of a key-access PUT operation is the cell specified 
by the RRN. 

• For an indexed file, a key-access PUT operation has no target; 
the PUT operation inserts the record and updates indexes. 

FORMAT 

The format for the $PUT is: 

$PUT rabaddr [ , [erraddr] [ ,sucaddr] ] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 

CONTROL BLOCKS 

You must supply a RAB for the PUT operation. 

OPTIONS 

Internal Stream Identifier 

The PUT operation reads the internal stream identifier from the 1-word 
ISI field of the RAB. 

Asynchronous Operation 

If you want to execute the PUT operation asynchronously, set the 
RB$ASY mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the PUT operation executes synchronously. (Your program 
must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 

Key Access 

Specify the RB$KEY code in the 1-byte RAC field of the RAB. 

Record 

Specify the address of the record to be transferred in the 1-word RBF 
field of the RAB, and the size (in bytes) of the record in the 1-word 
RSZ field of the RAB. 
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If the record is in VFC format, specify the address of the 
fixed-length portion of the record in the 1-word RHB field of the RAB. 
If you specify in this field, the record header will be null-filled. 

Record Buffer 

Specify a record buffer tor the PUT operation; specify the address of 
the record buffer in the 1-word UBF field of the RAB; specify the 
size (in bytes) of the record buffer in the 1-word USZ field of the 
RAB. 

Note that the value in the UBF field will be used (copied to the RBF 
field) only if you specify locate mode. A request for locate mode is 
otherwise ignored for a key access PUT operation. 

RRN 

For a relative file or for a sequential disk file with fixed-length 
records, specify a 4-byte relative record number (RRN) in the 1-word 
KBF field of the RAB, and specify or 4 in the 1-byte KSZ field of 
the RAB . 

Bucket Fill Number Honoring 

If you want the PUT operation to honor bucket fill numbers for the 
file and its areas, set the RB$LOA mask in the 1-word ROP field of the 
RAB. If you do not set this mask, the PUT operation fills buckets 
without regard to bucket fill numbers. 

Update Existing Record (Relative File) 

If you want to transfer the record to a cell in a relative file even 

if the cell contains a record, set the RB$UIF mask in the 1-word ROP 

field of the RAB. If you do not set this mask, and if the cell 

already contains a record, the PUT operation returns an error 
completion and does not transfer the record. 

STREAM CONTEXT 

The current-record context after a key access PUT operation is 
undefined; the next-record context is unchanged. 



RETURNED VALUES 



RRN 

For a relative file or for a sequential disk file with fixed-length 
records, a key-access PUT operation returns the relative record number 
(RRN) for the inserted record in the 2-word BKT field of the RAB. 



RFA 



The PUT operation returns the record file address 
inserted record in the 3-word RFA field of the RAB. 



(RFA) for the 
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Completion Status and Value 

The PUT operation returns completion status in the 1-word STS field of 
the RAB and returns a completion value in the 1-word STV field of the 
RAB. Appendix A lists completion status symbols and values. 

CHECKLISTS 

Table 5-43 lists control block fields that are input to the PUT 
operation. Table 5-44 lists control block fields that are output by 
the PUT operation. 



Table 5-43: PUT (Key Access) Input Fields 



Block Field Description 



RAB 


ISI 


RAB 


KBF 


RAB 


KSZ 


RAB 


RAC 



Internal stream identifier 
Key buffer address 
Key size (bytes) 
Record access code 



RB$KEY 



Key access 



RAB RBF Record buffer address 

RAB RHB VFC control buffer address 

RAB ROP Record processing option mask 

RB$ASY Asynchronous operation 

RB$LOA Honor bucket fill numbers 

RB$LOC Locate mode 

RB$UIF Update if record exists 



RAB RSZ Record size (bytes) 
RAB UBF User buffer address 
RAB USZ User buffer size (bytes) 



Table 5-44: PUT (Key Access) Output Fields 



Block Field Description 



RAB 


BKT 


RAB 


RBF 


RAB 


RFA 


RAB 


STS 


RAB 


STV 



Relative record number (RRN) 
Record buffer address 
Record file address 
Completion status code 
Completion status value 
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5.23 $READ MACRO (SEQUENTIAL ACCESS) 

The $READ macro calls the READ operation routine to transfer blocks 
from a file to an I/O buffer. The target of a sequential-access READ 
operation is the readable block (and, for a multiblock READ operation, 
following blocks) . 

FORMAT 

The format for the $READ is: 

$READ rabaddr [ , [erraddr] [ ,sucaddr] ] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 

CONTROL BLOCKS 

You must supply a RAB for the READ operation. 

OPTIONS 

Internal Stream Identifier 

The READ operation reads the internal stream identifier from the 
1-word ISI field of the RAB. 

Block Specification 

For a sequential-access READ operation, specify in the 2-word BKT 
field of the RAB. 

User Buffer 

Specify the address of the user buffer in the 1-word UBF field of the 
RAB, and specify the size (in bytes) of the user buffer in the 1-word 
USZ field of the RAB. 

For a magtape file, the READ operation reads at most one magtape block 
into the buffer; for other files, the READ operation fills the buffer 
(unless it reached the end-of-file before the buffer is filled) . 

Asynchronous Operation 

If you want to execute the READ operation asynchronously, set the 
RB$ASY mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the READ operation executes synchronously. (Your program 
must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 

STREAM CONTEXT 

The readable-block context after a READ operation is the block 
following the last-read block; the writable-block context is the 
first-read block. 
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RETURNED VALUES 



Data Blocks 



The READ operation returns the address and length of the data read 
from the file. The value in the 1-word RBF field of the RAB is the 
address of the data read; the value in the 1-word RSZ field of the 
RAB is the length (in bytes) of the data read. 

The READ operation normally will not read beyond the logical 
end-of-file. For sequential files with undefined (UDF) record format, 
however, the READ operation will respect the logical end-of-file 
marker only if you have specified no write-sharing in the 1-byte SHR 
field of the FAB. If you specify write-sharing, RMS-11 will ignore 
the logical end-of-file marker and will stop only at the physical 
end-of-file on the disk. 

Record File Address (RFA) 

The READ operation returns the virtual block number of the first-read 
block in the first two words of the 3-word RFA field of the RAB (it 
clears the third word) . 

Completion Status and Value 

The READ operation returns completion status in the 1-word STS field 
of the RAB and returns a completion value in the 1-word STV field of 
the RAB. Appendix A lists completion status symbols and values. 

CHECKLISTS 

Table 5-45 lists control block fields that are input to the READ 
operation. Table 5-46 lists control block fields that are output by 
the READ operation. 

Table 5-45: READ (Sequential Access) Input Fields 



Block Field Description 



RAB BKT Virtual block number (VBN) 
RAB ISI Internal stream identifier 
RAB ROP Record processing option mask 

RB$ASY Asynchronous operation 

RAB UBF User buffer address 

RAB USZ User buffer size (bytes) 



Table 5-46: READ (Sequential Access) Output Fields 



Block Field Description 



RAB RBF Record buffer address 

RAB RFA Virtual block number (2 words) 

RAB RSZ Record size (bytes) 

RAB STS Completion status code 

RAB STV Completion status value 
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5.24 $READ MACRO (VBN ACCESS) 

The $READ macro calls the READ operation routine to transfer blocks 
from a file to an I/O buffer. The target of a VBN-access READ 
operation is a specified block (and, for a multiblock READ operation, 
following blocks) . 

FORMAT 

The format for the $READ is: 

$READ rabaddr [ , [erraddr] [ ,sucaddr] ] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 

CONTROL BLOCKS 

You must supply a RAB for the READ operation. 

OPTIONS 

Internal Stream Identifier 

The READ operation reads the internal stream identifier from the 
1-word ISI field of the RAB. 

Block Specification 

Specify the virtual block number of the first block to be read in the 
2-word BKT field of the RAB. 

Dser Buffer 

Specify the address of the user buffer in the 1-word UBF field of the 
RAB, and specify the size (in bytes) of the user buffer in the 1-word 
USZ field of the RAB. 

For a magtape file, the READ operation reads at most one magtape block 
into the buffer; for other files, the READ operation fills the buffer 
(unless it reached the end-of-file before the buffer is filled) . 

Asynchronous Operation 

If you want to execute the READ operation asynchronously, set the 
RB$ASY mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the READ operation executes synchronously. (Your program 
must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 

STREAM CONTEXT 

The readable-block context after a READ operation is the block 
following the last-read block; the writable-block context is the 
first-read block. 
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RETURNED VALUES 



Data Blocks 

The READ operation returns the address and length of the data read 
from the file. The value in the 1-word RBF field of the RAB is the 
address of the data read; the value in the 1-word RSZ field of the 
RAB is the length (in bytes) of the data read. 

The READ operation normally will not read beyond the logical 
end-of-file. For sequential files with undefined (UDF) record format, 
however, the READ operation will respect the logical end-of-file 
marker only if you have specified no write-sharing in the 1-byte SHR 
field of the FAB. If you specify write-sharing, RMS-11 will ignore 
the logical end-of-file marker and will stop only at the physical 
end-of-file on the disk. 

Record File Address (RFA) 

The READ operation returns the virtual block number of the first-read 
block in the first two words of the 3-word RFA field of the RAB (it 
clears the third word) . 

Completion Status and Value 

The READ operation returns completion status in the 1-word STS field 
of the RAB and returns a completion value in the 1-word STV field of 
the RAB. Appendix A lists completion status symbols and values. 

CHECKLISTS 

Table 5-47 lists control block fields that are input to the READ 
operation. Table 5-48 lists control block fields that are output by 
the READ operation. 



Table 5-47: READ (VBN Access) Input Fields 



Block Field Description 



RAB 


BKT 


RAB 


ISI 


RAB 


ROP 



RAB 
RAB 



DBF 
USZ 



Virtual block number (VBN) 
Internal stream identifier 
Record processing option mask 

RB$ASY Asynchronous operation 

User buffer address 
User buffer size (bytes) 



Table 5-48: READ (VBN Access) Output Fields 



Block Field Description 



RAB 


RBF 


RAB 


RFA 


RAB 


RSZ 


RAB 


STS 


RAB 


STV 



Record buffer address 
Virtual block number (2 words) 
Record size (bytes) 
Completion status code 
Completion status value 
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5.25 $ REMOVE MACRO 

The $REMOVE macro calls the REMOVE operation routine to remove the 
directory entry for a file. 

FORMAT 

The format for the $REMOVE is: 

$REMOVE f abaddr [ , [erraddr] [ ,sucaddr] ] 

where fabaddr is the address of the FAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 

CONTROL BLOCKS 

You must supply a FAB for the REMOVE operation. 

If you supply a NAM block and specify remove by NAM block, the REMOVE 
operation reads NAM block fields to obtain identifiers for the target 
file. 

To supply a NAM block for the REMOVE operation, specify the address of 
the NAM block in the 1-word NAM field of the FAB. 

To supply XABs (ALL, DAT, KEY, PRO, and SUM blocks) for the REMOVE 
operation, specify the address of the first XAB in the 1-word XAB 
field of the FAB; specify the address of the next XAB (if any) in the 
1-word NXT field of each XAB; specify in the NXT field of the last 
XAB. 

All KEY blocks must be together in the chain of XABs, and must be in 
ascending order (by the index reference number in the 1-byte REF field 
of the KEY block) ; the index reference numbers need not be 
consecutive. 

All ALL blocks must be together in the chain of XABs, and must be in 
ascending order (by the area identifier in the 1-byte AID field of the 
ALL block); the area identifiers need not be consecutive. 

Multiple DAT, PRO, or SUM XABs are illegal. 
OPTIONS 

File Specification (Nonwildcard REMOVE Operation) 

The REMOVE operation constructs the full file specification from the 
file string, the default string (which contributes only elements not 
present in the file string) , and RMS-11 defaults (which contribute 
elements not present in either the file string or the default string) . 
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RMS-11 defaults are: 

Device — The device to which the specified logical channel is 
assigned, or SY: if the specified logical channel is not 
assigned to any device. 

• Directory — The current directory for the task. 

• Name, type, version — Defaulted to null. 

The file string and the default string must not contain wildcards. 

Specify the address of the file string in the 1-word FNA field of the 

FAB. Specify the size (in bytes) of the file string in the 1-byte FNS 

field of the FAB; if you specify in the FNS field, the REMOVE 
operation uses no file string. 

Specify the address of the default string in the 1-word DNA field of 

the FAB. Specify the size (in bytes) of the default string in the 

1-byte DNS field of the FAB; if you specify in the DNS field, the 
REMOVE operation uses no default string. 

If you set the FB$FID mask in the 1-word FOP field of the FAB and 
supply a NAM block, the REMOVE operation reads the device identifier 
from the 2-word DVI field of the NAM block; if this value is nonzero, 
the specified device overrides the device in the merged string. 

In the same circumstance, the REMOVE operation reads the directory 
identifier from the 3-word DID field of the NAM block; if this value 
is nonzero, the specified directory overrides the directory in the 
merged string. 

Remove by Wildcard Specification 

You can use the REMOVE operation in a wildcarding program loop. (The 
NB$WCH mask in the 1-word FNB field of the NAM block will already have 
been set by an earlier PARSE operation.) 

If you set the FB$FID mask in the 1-word FOP field of the FAB, the 
file found by a previous SEARCH operation is removed without affecting 
fields that are used as context for subsequent SEARCH operations. 

If you clear the FB$FID mask in the 1-word FOP field of the FAB, the 
REMOVE operation first performs an implicit SEARCH operation. (The 
input and output fields for the SEARCH operation are not described 
here and are not included in the checklists at the end of this 
section.) 

If the SEARCH operation finds a file that matches the wildcard file 
specification, the REMOVE operation removes its directory entry; if 
not, the REMOVE operation does not remove a directory entry, but 
instead passes control block data from the SEARCH operation (in 
particular, the ER$NMF completion status code and the cleared NB$WCH 
mask in the 1-word FNB field of the NAM block) . 
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Expanded String Buffer 

If you want the REMOVE operation to return the expanded string for the 

file whose directory entry was removed, provide a buffer for the 

string. Specify the address of the expanded string buffer in the 

1-word ESA field of the NAM block. Specify the size (in bytes) of the 

expanded string buffer in the 1-byte ESS field of the NAM block; if 
you specify in the ESS field, the REMOVE operation does not return 
the expanded string. 

Private Buffer Pool 

If you want the REMOVE operation to use a private buffer pool instead 
of the central buffer pool, specify the address of the (word-aligned) 
private buffer pool in the 1-word BPA field of the FAB, and its size 
(in bytes) in the 1-word BPS field of the FAB; this size must be a 
multiple of 4. 

If you specify in either the BPA field or the BPS field, the REMOVE 
operation uses the central buffer pool. 

Logical Channel 

Specify the logical channel for the REMOVE operation in the 1-byte LCH 

field of the FAB. The logical channel number must not be the same as 

the logical channel number for any already-open file, and must not be 
0. 



RETURNED VALUES 

Device Characteristics 

The REMOVE operation returns device characteristics as masks in the 
1-byte DEV field of the FAB. The device characteristics are: 

• Printer or terminal (indicated by the set FB$CCL mask in the 
1-byte DEV field of the FAB and the set FB$REC mask in the 
1-byte DEV field of the FAB; for a terminal, the FB$TRM mask 
in the 1-byte DEV field of the FAB is also set) ; RMS-11 
treats a printer or terminal as a unit-record device. 

• Disk, DECtape, or DECTAPE II (indicated by the set FB$MDI mask 
in the 1-byte DEV field of the FAB); RMS-11 treats a disk, 
DECtape, or DECTAPE II as a disk device. 

• Unit-record device (indicated by the set FB$REC mask in the 
1-byte DEV field of the FAB) . 

• Non-ANSI magtape or cassette tape (indicated by the set FB$SDI 
mask in the 1-byte DEV field of the FAB and the set FB$REC 
mask in the 1-byte DEV field of the FAB) ; RMS-11 treats a 
non-ANSI magtape or a cassette tape as a unit-record device. 

ANSI-format magtape (indicated by the set FB$SQD mask in the 
1-byte DEV field of the FAB) . 
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Device, Directory, and File Identifiers 

If you supply a NAM block, the REMOVE operation writes a device 
identifier in the 2-word DVI field of the NAM block, a directory 
identifier in the 3-word DID field of the NAM block, and a file 
identifier in the 3-word FID field of the NAM block. 

Expanded String 

If you specify a buffer for the expanded string for the file (ESA and 
ESS fields in the NAM block) , the REMOVE operation writes the expanded 
string for the target file in this buffer, and writes the length (in 
bytes) of the string in the 1-byte ESL field of the NAM block. 

File Specification Characteristics 

The REMOVE operation sets the masks in the 1-word FNB field of the NAM 
block to show which file specification elements were present in the 
file string and default string. 

These masks and their meaning are: 

NB$NOD Node in file string or default string 

NB$DEV Device in file string or default string 

NB$DIR Directory in file string or default string 

NB$QUO Quoted string in file string or default string 

NB$NAM File name in file string or default string 

NB$TYP File type in file string or default string 

NB$VER File version in file string or default string 

NB$WDI Wildcard directory in file string or default string 

NB$WNA Wildcard file name in file string or default string 

NB$WTY Wildcard file type in file string or default string 

NB$WVE Wildcard file version in file string or default string 

Wildcarding 

The REMOVE operation clears the NB$WCH mask in the 1-word FNB field of 
the NAM block; this shows that no wildcard context exists after the 
REMOVE operation. It also clears the 1-byte RSL field of the NAM 
block to show that no resultant string was returned. 

Completion Status and Value 

The REMOVE operation returns completion status in the 1-word STS field 
of the FAB and returns a completion value in the 1-word STV field of 
the FAB. Appendix A lists completion status symbols and values. 

CHECKLISTS 

Table 5-49 lists control block fields that are input to the REMOVE 
operation. Table 5-50 lists control block fields that are output by 
the REMOVE operation. 
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Table 5-49: REMOVE Input Fields 



Block Field Description 



ALL 


NXT 


DAT 


NXT 


FAB 


BPA 


FAB 


BPS 


FAB 


DNA 


FAB 


DNS 


FAB 


FNA 


FAB 


FNS 


FAB 


FOP 



FAB 


LCH 


FAB 


NAM 


KEY 


NXT 


NAM 


DID 


NAM 


DVI 


NAM 


ESA 


NAM 


ESS 


NAM 


FID 


NAM 


FNB 



Next XAB address 

Next XAB address 

Private buffer pool address 

Private buffer pool size (bytes) 

Default string address 

Default string size (bytes) 

File string address 

File string size (bytes) 

File processing option mask 

FB$FID Use information in NAM block 

Logical channel number 

NAM block address 

Next XAB address 

Directory identifier 

Device identifier 

Expanded string buffer address 

Expanded string buffer size (bytes) 

File identifier 

File specification mask 



NB$WCH 



Wildcard context established 



PRO NXT Next XAB address 
SUM NXT Next XAB address 



Table 5-50: REMOVE Output Fields 



Block Field Description 



FAB 



DEV 



Device characteristic mask 



FB$CCL Carriage-control device 

FB$MDI Multidirectory device 

FB$REC Record-oriented device 

FB$SDI Single-directory device 

FB$SQD Sequential device 

FB$TRM Terminal device 

FAB STS Completion status code 

FAB STV Completion status value 

NAM DID Directory identifier 

NAM DVI Device identifier 

NAM ESL Expanded string length (bytes) 

NAM FID File identifier 



(Continued on next page) 
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Table 5-50 (Cont.): REMOVE Output Fields 



Block Field Description 



NAM FNB File specification mask 

NB$NOD Node in file string or default string 
NB$DEV Device in file string or default string 
NB$DIR Directory in file string or default string 
NB$QUO Quoted string in file string or default 

string 
NB$NAM File name in file string or default string 
NB$TYP File type in file string or default string 
NB$VER File version in file string or default 

string 
NB$WDI Wildcard directory in file string or 

default string 
NB$WNA Wildcard file name in file string or 

default string 
NB$WTY Wildcard file type in file string or 

default string 
NB$WVE Wildcard file version in file string or 

default string 
NB$WCH Wildcard context established (cleared) 

NAM RSL Resultant string length (bytes) 
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5.26 $RENAME MACRO 

The $RENAME macro calls the RENAME operation routine to change the 
directory entry for a file. 

The old and new entries (file specifications) must have the same 
network node and device specifications. 

FORMAT 

The format for the $RENAME is: 

$RENAME oldfabaddr , [erraddr] , [sucaddr] ,newfabaddr 

where oldfabaddr is the address of the FAB for the operation; erraddr 
is the address of the error handler for the operation; sucaddr is the 
address of the success handler for the operation; and newfabaddr is 
the address of the FAB giving the new file specification. 

CONTROL BLOCKS 

You must supply two FABs for the RENAME operation: an "old" FAB 
containing the current specification for the file, and a "new" FAB 
containing the new specification for the file. 

If you supply a NAM block for the old FAB (old NAM block) and specify 
either rename by NAM block or wildcarding, the RENAME operation reads 
its fields to obtain identifiers for the old file specification. If 
you supply a NAM block for the new FAB (new NAM block) and specify 
rename by NAM block, the RENAME operation reads its fields to obtain 
identifiers for the new file specification. 

To supply a NAM block for the RENAME operation, specify the address of 
the NAM block in the 1-word NAM field of the FAB. 

To supply XABs (ALL, DAT, KEY, PRO, and SUM blocks) for the RENAME 
operation, specify the address of the first XAB in the 1-word XAB 
field of the FAB; specify the address of the next XAB (if any) in the 
1-word NXT field of each XAB; specify in the NXT field of the last 
XAB. 

All KEY blocks must be together in the chain of XABs, and must be in 
ascending order (by the index reference number in the 1-byte REF field 
of the KEY block) ; the index reference numbers need not be 
consecutive. 

All ALL blocks must be together in the chain of XABs, and must be in 
ascending order (by the area identifier in the 1-byte AID field of the 
ALL block) ; the area identifiers need not be consecutive. 

Multiple DAT, PRO, or SUM XABs are illegal. 
OPTIONS 

Old File Specification (Nonwildcatu RENAME Operation) 

The RENAME operation constructs the full file specification from the 
file string, the default string (which contributes only elements not 
present in the file string) , and RMS-11 defaults (which contribute 
elements not present in either the file string or the default string) . 
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RMS-11 defaults are: 

Device — The device to which the specified logical channel is 
assigned, or SY: if the specified logical channel is not 
assigned to any device. 

• Directory — The current directory for the task. 

• Name, type, version — Defaulted to null. 

The file string and the default string must not contain wildcards. 

Specify the address of the file string in the 1-word FNA field of the 

FAB. Specify the size (in bytes) of the file string in the 1-byte FNS 

field of the FAB; if you specify in the FNS field, the RENAME 
operation uses no file string. 

Specify the address of the default string in the 1-word DNA field of 

the FAB. Specify the size (in bytes) of the default string in the 

1-byte DNS field of the FAB; if you specify in the DNS field, the 
RENAME operation uses no default string. 

If you set the FB$FID mask in the 1-word FOP field of the FAB and 
supply a NAM block, the RENAME operation reads the device identifier 
from the 2-word DVI field of the NAM block; if this value is nonzero, 
the specified device overrides the device in the merged string. 

In the same circumstance, the RENAME operation reads the directory 
identifier from the 3-word DID field of the NAM block; if this value 
is nonzero, the specified directory overrides the directory in the 
merged string. 

Old File Specification (Wildcard RENAME Operation) 

You can use the RENAME operation in a wildcarding program loop. (The 
NB$WCH mask in the 1-word FNB field of the NAM block will already have 
been set by an earlier PARSE operation.) 

If you set the FB$FID mask in the 1-word FOP field of the FAB, the 
file found by a previous SEARCH operation is renamed without affecting 
fields that are used as context for subsequent SEARCH operations. 

If you clear the FB$FID mask in the 1-word FOP field of the FAB, the 
RENAME operation first performs an implicit SEARCH operation. (The 
input and output fields for the SEARCH operation are not described 
here and are not included in the checklists at the end of this 
section . ) 

If the SEARCH operation finds a file that matches the wildcard file 
specification, the RENAME operation replaces its directory entry; if 
not, the RENAME operation does not replace a directory entry, but 
instead passes control block data from the SEARCH operation (in 
particular, the ER$NMF completion status code and the cleared NB$WCH 
mask in the 1-word FNB field of the NAM block) . 

New File Specification 

The RENAME operation constructs the full file specification from the 
file string, the default string (which contributes only elements not 
present in the file string) , and RMS-11 defaults (which contribute 
elements not present in either the file string or the default string) . 
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RMS-11 defaults are: 



Device — The device that was used for the old file 
specification (The old FAB logical channel is used, and the 
new FAB logical channel is ignored) . 

• Directory -- The current directory for the task. 

• Name, type, version — Defaulted to null. 

The file string and the default string must not contain wildcards. 

Specify the address of the file string in the 1-word FNA field of the 
FAB. Specify the size (in bytes) of the file string in the 1-byte FNS 
field of the FAB; if you specify in the FNS field, the RENAME 
operation uses no file string. 

Specify the address of the default string in the 1-word DNA field of 

the FAB. Specify the size (in bytes) of the default string in the 

1-byte DNS field of the FAB; if you specify in the DNS field, the 
RENAME operation uses no default string. 

If you set the FB$FID mask in the 1-word FOP field of the FAB and 
supply a NAM block, the RENAME operation reads the device identifier 
from the 2-word DVI field of the NAM block; if this value is nonzero, 
the specified device overrides the device in the merged string. 

In the same circumstance, the RENAME operation reads the directory 
identifier from the 3-word DID field of the NAM block; if this value 
is nonzero, the specified directory overrides the directory in the 
merged string. 

Private Buffer Pool 

If you want the RENAME operation to use a private buffer pool instead 
of the central buffer pool, specify the address of the (word-aligned) 
private buffer pool in the 1-word BPA field of the FAB, and its size 
(in bytes) in the 1-word BPS field of the FAB; this size must be a 
multiple of 4. 

If you specify in either the BPA field or the BPS field, the RENAME 
operation uses the central buffer pool. 

Logical Channel 

Specify the logical channel for the RENAME operation in the 1-byte LCH 
field of the FAB. The logical channel number must not be the same as 
the logical channel number for any already-open file, and must not be 
0. 

Expanded String Buffers 

If you want the expanded string for the file given by a FAB returned 
to a buffer, supply a NAM block for the FAB. Specify the address of 
the buffer in the 1-word ESA field of the NAM block, and the size (in 
bytes) of the buffer in the 1-byte ESS field of the NAM block. If you 
do not supply a NAM block for a FAB, or if you specify in the ESS 
field, the RENAME operation does not return the expanded string. 
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RETURNED VALUES 



Expanded Strings 

If you specify a buffer for the expanded string for a FAB (ESA and ESS 
fields in the NAM block) , the RENAME operation writes the expanded 
string in the buffer, and writes the length (in bytes) of the string 
in the 1-byte ESL field of the NAM block. 



Device Characteristics 

The RENAME operation returns device characteristics as masks 
1-byte DEV field of the FAB. The device characteristics are: 



the 



• Printer or terminal (indicated by the set FB$CCL mask in the 
1-byte DEV field of the FAB and the set FB$REC mask in the 
1-byte DEV field of the FAB; for a terminal, the FB$TRM mask 
in the 1-byte DEV field of the FAB is also set); RMS-11 
treats a printer or terminal as a unit-record device. 

• Disk, DECtape, or DECTAPE II (indicated by the set FB$MDI mask 
in the 1-byte DEV field of the FAB); RMS-11 treats a disk, 
DECtape, or DECTAPE II as a disk device. 



• Unit-record device (indicated by the set FB$REC mask 
1-byte DEV field of the FAB) . 



in 



the 



• Non-ANSI magtape or cassette tape (indicated by the set FB$SDI 
mask in the 1-byte DEV field of the FAB and the set FB$REC 
mask in the 1-byte DEV field of the FAB) ; RMS-11 treats a 
non-ANSI magtape or a cassette tape as a unit-record device. 

• ANSI-format magtape (indicated by the set FB$SQD mask in the 
1-byte DEV field of the FAB) . 



Device, Directory, and File Identifiers 



If you supply a NAM block, the RENAME operation writes a device 
identifier in the 2-word DVI field of the NAM block, a directory 
identifier in the 3-word DID field of the NAM block, and a file 
identifier in the 3-word FID field of the NAM block. 



File Specification Characteristics 



The RENAME operation sets masks in the 1-word FNB field of the NAM 
block to show which file specification elements were present in the 
file string and default string. 

These masks and their meaning are: 

NB$NOD Node in file string or default string 

NB$DEV Device in file string or default string 

NB$DIR Directory in file string or default string 

NB$QUO Quoted string in file string or default string 

NB$NAM File name in file string or default string 

NB$TYP File type in file string or default string 

NB$VER File version in file string or default string 

NB$WDI Wildcard directory in file string or default string 

^ NB$WNA Wildcard file name in file string or default string 

NB$WTY Wildcard file type in file string or default string 

NB$WVE Wildcard file version in file string or default string 
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Wildcarding 

The RENAME operation clears the NB$WCH mask in the 1-word FNB field of 
the NAM block; this shows that no wildcard context exists after the 
RENAME operation. It also clears the 1-byte RSL field of the NAM 
block to show that no resultant string was returned. 

Completion Status and Value 

The RENAME operation returns completion status in the 1-word STS field 
of the FAB and returns a completion value in the 1-word STV field of 
the FAB. Appendix A lists completion status symbols and values. 

CHECKLISTS 

Table 5-51 lists control block fields that are input to the RENAME 
operation. Table 5-52 lists control block fields that are output by 
the RENAME operation. 

NOTE 

The only input fields taken from both 
the "old" and the "new" FABs are the 
DNA, DNS, FNA, FNS, FOP, and NAM fields. 
All other FAB input fields are taken 
from the "old" FAB only. All FAB output 
fields are returned to the "old" FAB 
only. 

Table 5-51: RENAME Input Fields 



Block Field Description 



ALL 


NXT 


DAT 


NXT 


FAB 


BPA 


FAB 


BPS 


FAB 


DNA 


FAB 


DNS 


FAB 


FNA 


FAB 


FNS 


FAB 


FOP 



Next XAB address 

Next XAB address 

Private buffer pool address 

Private buffer pool size (bytes) 

Default string address 

Default string size (bytes) 

File string address 

File string size (bytes) 

File processing option mask 

FB$FID Use information in NAM block 

Logical channel number 

NAM block address 

Next XAB address 

Directory identifier 

Device identifier 

Expanded string buffer address 

Expanded string buffer size (bytes) 

File specification mask 

NB$WCH Wildcard context established 



FAB 


LCH 


FAB 


NAM 


KEY 


NXT 


NAM 


DID 


NAM 


DVI 


NAM 


ESA 


NAM 


ESS 


NAM 


FNB 



PRO NXT Next XAB address 
SUM NXT Next XAB address 
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Table 5-52: RENAME Output Fields 



Block Field Description 



FAB 



DEV 



FAB 
FAB 
NAM 
NAM 
NAM 
NAM 
NAM 



STS 
STV 
DID 
DVI 
ESL 
FID 
FNB 



Device characteristic mask 

FB$CCL Carriage-control device 

FB$MDI Multidirectory device 

FB$REC Record-oriented device 

FB$SDI Single-directory device 

FB$SQD Sequential device 

FB$TRM Terminal device 

Completion status code 

Completion status value 

Directory identifier 

Device identifier 

Expanded string length (bytes) 

File identifier 

File specification mask 



NB$NOD 
NB$DEV 
NB$DIR 
NB$QUO 

NB$NAM 
NB$TYP 
NB$VER 

NB$WDI 

NB$WNA 

NB$WTY 

NB$WVE 

NB$WCH 



Node in file string or default 

Device in file string or defaul 

Directory in file string or def 

Quoted string in file string 

string 

File name in file string or def 

File type in file string or def 

File version in file string 

string 

Wildcard directory in 

default string 



string 
t string 
ault string 
or default 

ault string 
ault string 
or default 



name in 



type 



in 



Wildcard file 

default string 

Wildcard file 

default string 

Wildcard file version 

default string 

Wildcard context established (c 



in 



file 
file 
file 
file 



string or 

string or 

string or 

string or 

:leared) 



NAM 



RSL 



Resultant string length (bytes) 
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5.27 $ REWIND MACRO 

The $REWIND macro calls the REWIND operation routine to reset the 
context for a stream to the beginning-of-f ile. The file can have any 
organization. 

FORMAT 

The format for the $REWIND is: 

$REWIND rabaddr[, [erraddr] [,sucaddr] ] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 

CONTROL BLOCKS 

You must supply a RAB for the REWIND operation. 

OPTIONS 

Internal Stream Identifier 

The REWIND operation reads the internal stream identifier from the 
1-word ISI field of the RAB. 

Key of Reference 

For an indexed file, you must specify the index that the stream will 
use in accessing records. Specify this key of reference in the 1-byte 
KRF field of the RAB. This value matches the value in the file's KEY 
block for the index: for the primary index, 1 for the first 
alternate index, and so forth. 

Asynchronous Operation 

If you want to execute the REWIND operation asynchronously, set the 
RB$ASY mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the REWIND operation executes synchronously. (Your program 
must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 

STREAM CONTEXT 

For a record access file, the current context after a REWIND operation 
is undefined and the next-record context is the first record in the 
file; for an indexed file, this first record is defined by the 
specified index. 

For a block access file, both the readable-block and writable-block 
contexts after a REWIND operation are the first block in the file. 
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RETURNED VALUES 



Completion Status and Value 

The REWIND operation returns completion status in the 1-word STS field 
of the RAB and returns a completion value in the 1-word STV field of 
the RAB. Appendix A lists completion status symbols and values. 

CHECKLISTS 

Table 5-53 lists control block fields that are input to the REWIND 
operation. Table 5-54 lists control block fields that are output by 
the REWIND operation. 



Table 5-53: REWIND Input Fields 



Block Field Description 



RAB ISI Internal stream identifier 

RAB KRF Key of reference 

RAB ROP Record processing option mask 

RB$ASY Asynchronous operation 



Table 5-54: REWIND Output Fields 



Block Field Description 



RAB STS Completion status code 
RAB STV Completion status value 
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5.28 $SEARCH MACRO 



The $SEARCH macro calls the SEARCH operation routine to scan a 
directory and return a file specification and identifiers in NAM block 
fields. You should precede the SEARCH operation by a PARSE operation, 
which initializes the NAM block fields for the SEARCH operation. 

The SEARCH operation finds a file specification that matches the 
match-pattern initialized (in the expanded string buffer) by the PARSE 
operation; a series of wildcard SEARCH operations returns successive 
matching file specifications. 

FORMAT 

The format for the $SEARCH is: 

$SEARCH fabaddr [ , [erraddr] [ , sucaddr] ] 

where fabaddr is the address of the FAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 

CONTROL BLOCKS 

You must supply a FAB for the SEARCH operation. 

You must supply a NAM block for the SEARCH operation. 

To supply a NAM block for the SEARCH operation, specify the address of 
the NAM block in the 1-word NAM field of the FAB. 

To supply XABs (ALL, DAT, KEY, PRO, and SUM blocks) for the SEARCH 
operation, specify the address of the first XAB in the 1-word XAB 
field of the FAB; specify the address of the next XAB (if any) in the 
1-word NXT field of each XAB; specify in the NXT field of the last 
XAB. 

All KEY blocks must be together in the chain of XABs, and must be in 
ascending order (by the index reference number in the 1-byte REF field 
of the KEY block) ; the index reference numbers need not be 
consecutive. 

All ALL blocks must be together in the chain of XABs, and must be in 
ascending order (by the area identifier in the 1-byte AID field of the 
ALL block); the area identifiers need not be consecutive. 

Multiple DAT, PRO, or SUM XABs are illegal. 
OPTIONS 

Wildcard Context Information 

The SEARCH operation reads NAM block fields that are initialized, 
written, or preserved by a preceding PARSE or wildcard SEARCH 

operation: the 3-word DID field of the NAM block, the 2-word DVI 

field of the NAM block, the 1-word ESA field of the NAM block, the 

1-byte ESL field of the NAM block, the NB$WCH mask in the 1-word FNB 

field of the NAM block, the 1-word RSA field of the NAM block, the 

1-byte RSL field of the NAM block, the 1-byte RSS field of the NAM 

block, the 1-word WCC field of the NAM block, and the 1-word WDI field 

of the NAM block. 
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The SEARCH operation also uses the expanded string in the expanded 
string buffer. 

You must preserve these fields between a PARSE and a SEARCH operation 
and between successive wildcard SEARCH operations. 

Private Buffer Pool 

If you want the SEARCH operation to use a private buffer pool instead 
of the central buffer pool, specify the address of the (word-aligned) 
private buffer pool in the 1-word BPA field of the FAB, and its size 
(in bytes) in the 1-word BPS field of the FAB; this size must be a 
multiple of 4. 

If you specify in either the BPA field or the BPS field, the SEARCH 
operation uses the central buffer pool. 

Logical Channel 

Specify the logical channel for the SEARCH operation in the 1-byte LCH 

field of the FAB. The logical channel number must not be the same as 

the logical channel number for any already-open file, and must not be 
0. 

Magtape Positioning 

The FB$RWO mask in the 1-word FOP field of the FAB may be set to cause 
a magtape to be rewound prior to the first wildcard SEARCH operation. 
To avoid unpredictable results, the FB$RWO mask in the 1-word FOP 
field of the FAB and FB$RWC mask in the 1-word FOP field of the FAB 
should not be set thereafter. 

RETURNED VALUES 

Resultant String 

The SEARCH operation writes the full file specification for the found 
file in the resultant string buffer, and writes the length of the 
string in the 1-byte RSL field of the NAM block. 

Device Characteristics 

The SEARCH operation returns device characteristics as masks in the 
1-byte DEV field of the FAB. The device characteristics are: 

• Printer or terminal (indicated by the set FB$CCL mask in the 
1-byte DEV field of the FAB and the set FB$REC mask in the 
1-byte DEV field of the FAB; for a terminal, the FB$TRM mask 
in the 1-byte DEV field of the FAB is also set); RMS-11 
treats a printer or terminal as a unit-record device. 

Disk, DECtape, or DECTAPE II (indicated by the set FB$MDI mask 
in the 1-byte DEV field of the FAB); RMS-11 treats a disk, 
DECtape, or DECTAPE II as a disk device. 

Unit-record device (indicated by the set FB$REC mask in the 
1-byte DEV field of the FAB). 
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Non-ANSI magtape or cassette tape (indicated by the set FB$SDI 
mask in the 1-byte DEV field of the FAB and the set FB$REC 
mask in the 1-byte DEV field of the FAB) ; RMS-11 treats a 
non-ANSI magtape or a cassette tape as a unit-record device. 



• ANSI-format magtape (indicated by the set FB$SQD mask 
1-byte DEV field of the FAB) . 



in 



the 



Directory and File Identifiers 

If the SEARCH operation finds a file that matches the wildcard 
pattern, it writes the directory identifier for the found file in the 
3-word DID field of the NAM block, and the file identifier in the 
3-word FID field of the NAM block. 

Wildcard Context Information 

The SEARCH operation writes the wildcard context in the 1-word WCC 
field of the NAM block, and the wildcard directory context in the 
1-word WDI field of the NAM block. 

If the SEARCH operation did not find a matching file, it clears the 
NB$WCH mask in the 1-word FNB field of the NAM block; this shows that 
no further wildcarding is possible using the current wildcard 
information. 

Completion Status and Value 

The SEARCH operation returns completion status in the 1-word STS field 
of the FAB and returns a completion value in the 1-word STV field of 
the FAB. Appendix A lists completion status symbols and values. 

CHECKLISTS 

Table 5-55 lists control block fields that are input to the SEARCH 
operation. Table 5-56 lists control block fields that are output by 
the SEARCH operation. 



Table 5-55: SEARCH Input Fields 



Block Field Description 



ALL 


NXT 


DAT 


NXT 


FAB 


BPA 


FAB 


BPS 


FAB 


FOP 



FAB LCH 
FAB NAM 
KEY NXT 



Next XAB address 

Next XAB address 

Private buffer pool address 

Private buffer pool size (bytes) 

File processing option mask 

FB$RWO Rewind magtape before operation 
FB$RWC Rewind magtape after closing file 

Logical channel number 
NAM block address 
Next XAB address 



(Continued on next page) 
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Table 5-55 (Cont.): SEARCH Input Fields 



Block Field Description 



NAM 


DID 


NAM 


DVI 


NAM 


ESA 


NAM 


ESL 


NAM 


FNB 



NAM 


RSA 


NAM 


RSL 


NAM 


RSS 


NAM 


WCC 


NAM 


WD I 


PRO 


NXT 


SUM 


NXT 



Directory identifier 

Device identifier 

Expanded string buffer address 

Expanded string length (bytes) 

File specification mask 

NB$WCH Wildcard context established 

Resultant string buffer address 

Resultant string length (bytes) 

Resultant string buffer size (bytes) 

Wildcard context 

Wildcard directory context 

Next XAB address 

Next XAB address 



Table 5-56: SEARCH Output Fields 



Block Field Description 



FAB 



DEV 



Device characteristic mask 



FB$CCL Carriage-control device 

FB$MDI Multidirectory device 

FB$REC Record-oriented device 

FB$SDI Single-directory device 

FB$SQD Sequential device 

FB$TRM Terminal device 

FAB STS Completion status code 

FAB STV Completion status value 

NAM DID Directory identifier 

NAM FID File identifier 

NAM FNB File specification mask 

NB$WCH Wildcard context established 

NAM RSL Resultant string length (bytes) 

NAM WCC Wildcard context 

NAM WDI Wildcard directory context 
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5.29 $ SPACE MACRO 

The $SPACE macro calls the SPACE operation routine to move a magtape 
backward or forward. 

FORMAT 

The format for the $SPACE is: 

$SPACE rabaddr [ , [erraddr] [ ,sucaddr] ] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 

CONTROL BLOCKS 

You must supply a RAB for the SPACE operation. 

OPTIONS 

Internal Stream Identifier 

The SPACE operation reads the internal stream identifier from the 
1-word ISI field of the RAB. 

Spacing Interval 

Specify the number of blocks to move the magtape in the first word of 
the 2-word BKT field of the RAB. A positive number spaces forward; a 
negative number spaces backward. 

Asynchronous Operation 

If you want to execute the SPACE operation asynchronously, set the 
RB$ASY mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the SPACE operation executes synchronously. (Your program 
must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 

STREAM CONTEXT 

The readable-block context after a SPACE operation is the target 
block; the writable-block context after a SPACE operation is the 
target block. 

RETURNED VALUES 

Completion Status and Value 

The SPACE operation returns completion status in the 1-word STS field 
of the RAB and returns a completion value in the 1-word STV field of 
the RAB. Appendix A lists completion status symbols and values. 
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CHECKLISTS 

Table 5-57 lists control block fields that are input to the SPACE 
operation. Table 5-58 lists control block fields that are output by 
the SPACE operation. 



Table 5-57: SPACE Input Fields 



Block Field Description 



RAB BKT Virtual block number (VBN) increment 
RAB ISI Internal stream identifier 
RAB ROP Record processing option mask 

RB$ASY Asynchronous operation 



Table 5-58: SPACE Output Fields 



Block Field Description 



RAB STS Completion status code 
RAB STV Completion status value 
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5.30 $TRONCATE MACRO 

The $TRUNCATE macro calls the TRUNCATE operation routine to remove 
records from the latter part of a sequential file; records are 
removed inclusively from the current record through the end-of-file. 
If the file cannot be truncated, the TRUNCATE operation returns an 
error completion and leaves the current-record context undefined and 
the next-record context unchanged. 

FORMAT 

The format for the $TRUNCATE is: 

$TRUNCATE rabaddr [ , [erraddr] [ ,sucaddr] ] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 

CONTROL BLOCKS 

You must supply a RAB for the TRUNCATE operation. 

OPTIONS 

Internal Stream Identifier 

The TRUNCATE operation reads the internal stream identifier from the 
1-word ISI field of the RAB. 

Asynchronous Operation 

If you want to execute the TRUNCATE operation asynchronously, set the 
RB$ASY mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the TRUNCATE operation executes synchronously. (Your 
program must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 

STREAM CONTEXT 

The TRUNCATE operation destroys the current-record context; the 
next-record context after the TRUNCATE operation is the end-of-file. 

RETURNED VALUES 

Completion Status and Value 

The TRUNCATE operation returns completion status in the 1-word STS 
field of the RAB and returns a completion value in the 1-word STV 
field of the RAB. Appendix A lists completion status symbols and 
values . 
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CHECKLISTS 

Table 5-59 lists control block fields that are input to the TRUNCATE 
operation. Table 5-60 lists control block fields that are output by 
the TRUNCATE operation. 

Table 5-59: TRUNCATE Input Fields 



Block Field Description 



RAB ISI Internal stream identifier 
RAB ROP Record processing option mask 







RB$ASY Asynchronous operation 


Table 5-60: TRUNCATE Output Fields 


Block 


Field 


Description 


RAB 
RAB 


STS 
STV 


Completion status code 
Completion status value 
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5.31 $ UPDATE MACRO 

The $UPDATE macro calls the UPDATE operation routine to transfer a 

record from a user buffer to a disk file (overwriting the existing 

record). The target of the UPDATE operation is the current record, 
which is overwritten. 

If no record (as specified in the RAB) can be transferred, the UPDATE 
operation returns an error completion. 

FORMAT 

The format for the $UPDATE is: 

$UPDATE rabaddr [ , [erraddr] [,sucaddr]] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 

CONTROL BLOCKS 

You must supply a RAB for the UPDATE operation. 

OPTIONS 

Internal Stream Identifier 

The UPDATE operation reads the internal stream identifier from the 
1-word ISI field of the RAB. 

Record Buffer 

Specify the address of the record buffer in the 1-word RBF field of 
the RAB, and specify the size (in bytes) of the record buffer in the 
1-word RSZ field of the RAB. For sequential files and for indexed 
files in which duplicate primary key values are permitted, the size of 
the buffer must be the same as the size of the existing record. 

If the file has VFC format, specify the address of the buffer for the 
VFC header in the 1-word RHB field of the RAB; if you specify zero in 
this field, the existing record header will remain unchanged. 

Asynchronous Operation 

If you want to execute the UPDATE operation asynchronously, set the 
RB$ASY mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the UPDATE operation executes synchronously. (Your program 
must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 

Bucket Fill Number Honoring 

If you want the UPDATE operation to honor bucket fill numbers for the 
file and its areas, set the RB$LOA mask in the 1-word ROP field of the 
RAB. If you do not set this mask, the UPDATE operation fills buckets 
without regard to bucket fill numbers. 
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STREAM CONTEXT 



The UPDATE operation destroys the current-record context; 
next-record context after the UPDATE operation is unchanged. 



the 



RETURNED VALUES 



Completion Status and Value 

The UPDATE operation returns completion status in the 1-word STS field 
of the RAB and returns a completion value in the 1-word STV field of 
the RAB. Appendix A lists completion status symbols and values. 

CHECKLISTS 

Table 5-61 lists control block fields that are input to the UPDATE 
operation. Table 5-62 lists control block fields that are output by 
the UPDATE operation. 



Table 5-61: UPDATE Input Fields 
Block Field Description 



RAB ISI Internal stream identifier 

RAB RBF Record buffer address 

RAB RHB VFC control buffer address 

RAB ROP Record processing option mask 

RB$ASY Asynchronous operation 
RB$LOA Honor bucket fill numbers 



RAB 


RSZ 


Record size (bytes) 


Table 5-62: UPDATE Output Fields 


Block 


Field 


Description 



RAB STS Completion status code 
RAB STV Completion status value 
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5.32 $WAIT MACRO 

The $WAIT macro calls the WAIT operation routine to suspend processing 
until an outstanding asynchronous operation on the stream is 
completed. The WAIT operation does not affect stream context. The 
WAIT operation cannot be used within any asynchronous operation's 
completion routine. 

FORMAT 

The format for the $WAIT is: 

$WAIT rabaddr 
where rabaddr is the address of the RAB for the operation. 

CONTROL BLOCKS 

You must supply a RAB for the WAIT operation. 

OPTIONS 

Internal Stream Identifier 

The WAIT operation reads the internal stream identifier from the 
1-word ISI field of the RAB. 

STREAM CONTEXT 

The WAIT operation does not affect stream context. The stream context 
after the WAIT operation is the context established by the outstanding 
asynchronous operation; if there is no outstanding asynchronous 
operation for the stream, the stream context is unchanged. 

RETURNED VALUES 

The WAIT operation returns no values. 

CHECKLISTS 

Table 5-63 lists control block fields that are input to the WAIT 
operation . 







Table 5-63: WAIT Input Fields 


Block 


Field 


Description 


RAB 


ISI 


Internal stream identifier 
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5.33 $WRITE MACRO (SEQUENTIAL ACCESS) 

The $WRITE macro calls the WRITE operation routine to write blocks to 
a file. The target of a sequential-access WRITE operation is the 
writable block (and, for a multiblock WRITE operation, following 
blocks) . 

FORMAT 

The format for the $WRITE is: 

$WRITE rabaddr [, [erraddr] [,sucaddr]] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 

CONTROL BLOCKS 

You must supply a RAB for the WRITE operation. 

OPTIONS 

Internal Stream Identifier 

The WRITE operation reads the internal stream identifier from the 
1-word ISI field of the RAB. 

Block Identification 

For a sequential-access WRITE operation, specify in the 2-word BKT 
field of the RAB. 

Record Buffer 

Specify the address of the record buffer in the 1-word RBF field of 
the RAB, and specify the size (in bytes) of the record buffer in the 
1-word RSZ field of the RAB. You must specify a record buffer for the 
WRITE operation; the WRITE operation transfers data from this buffer 
to the file. 

The WRITE operation normally updates the logical end-of-file marker, 
when appropriate, and automatically extends the file's allocation, 
when necessary. For sequential files with undefined (UDF) record 
format, however, the WRITE operation updates the logical end-of-file 
marker and performs automatic file extensions only if no write-sharing 
has been specified in the 1-byte SHR field of the FAB. 

Asynchronous Operation 

If you want to execute the WRITE operation asynchronously, set the 
RB$ASY mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the WRITE operation executes synchronously. (Your program 
must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 
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STREAM CONTEXT 



The readable-block context after a WRITE operation is the block 
following the last-written block; the writable-block context after a 
WRITE operation is the block following the last-written block. 



RETURNED VALUES 



Record File Address (RFA) 

The WRITE operation returns the virtual block number of the 
first-written block in the first two words of the 3-word RFA field of 
the RAB (it clears the third word) . 

Completion Status and Value 

The WRITE operation returns completion status in the 1-word STS field 
of the RAB and returns a completion value in the 1-word STV field of 
the RAB. Appendix A lists completion status symbols and values. 

CHECKLISTS 

Table 5-64 lists control block fields that are input to the WRITE 
operation. Table 5-65 lists control block fields that are output by 
the WRITE operation. 

Table 5-64: WRITE (Sequential Access) Input Fields 
Block Field Description 



RAB 


BKT 


RAB 


ISI 


RAB 


RBF 


RAB 


ROP 



RAB 



RSZ 



Virtual block number (VBN) 
Internal stream identifier 
Record buffer address 
Record processing option mask 

RB$ASY Asynchronous operation 

Record size (bytes) 



Table 5-65: WRITE (Sequential Access) Output Fields 
Block Field Description 



RAB RFA Virtual block number (2 words) 
RAB STS Completion status code 
RAB STV Completion status value 
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5.34 $WRITE MACRO (VBN ACCESS) 



The $WRITE macro calls the WRITE operation routine to write blocks to 
a file. The target of a VBN-access WRITE operation is the writable 
block (and, for a multiblock WRITE operation, following blocks). 

FORMAT 

The format for the $WRITE is: 

$WRITE rabaddr [ , [erraddr] [ ,sucaddr] ] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 

CONTROL BLOCKS 

You must supply a RAB for the WRITE operation. 

OPTIONS 

Internal Stream Identifier 

The WRITE operation reads the internal stream identifier from the 
1-word ISI field of the RAB. 

Block Identification 

Specify the virtual block number of the first block to be written in 
the 2-word BKT field of the RAB. 

Record Buffer 

Specify the address of the record buffer in the 1-word RBF field of 
the RAB, and specify the size (in bytes) of the record buffer in the 
1-word RSZ field of the RAB. You must specify a record buffer for the 
WRITE operation; the WRITE operation transfers data from this buffer 
to the file. 

The WRITE operation normally updates the logical end-of-file marker, 
when appropriate, and automatically extends the file's allocation, 
when necessary. For sequential files with undefined (UDF) record 
format, however, the WRITE operation updates the logical end-of-file 
marker and performs automatic file extensions only if no write-sharing 
has been specified in the 1-byte SHR field of the FAB. 

Asynchronous Operation 

If you want to execute the WRITE operation asynchronously, set the 
RB$ASY mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the WRITE operation executes synchronously. (Your program 
must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 
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STREAM CONTEXT 

The readable-block context after a WRITE operation is the block 
following the last-written block; the writable-block context after a 
WRITE operation is the block following the last-written block. 

RETURNED VALUES 

Record File Address (RFA) 

The WRITE operation returns the virtual block number of the 
first-written block in the first two words of the 3-word RFA field of 
the RAB (it clears the third word) . 

Completion Status and Value 

The WRITE operation returns completion status in the 1-word STS field 
of the RAB and returns a completion value in the 1-word STV field of 
the RAB. Appendix A lists completion status symbols and values. 

CHECKLISTS 

Table 5-66 lists control block fields that are input to the WRITE 
operation. Table 5-67 lists control block fields that are output by 
the WRITE operation. 

Table 5-66: WRITE (VBN Access) Input Fields 
Block Field Description 

RAB BKT Virtual block number (VBN) 

RAB ISI Internal stream identifier 

RAB RBF Record buffer address 

RAB ROP Record processing option mask 

RB$ASY Asynchronous operation 

RAB RSZ Record size (bytes) 

Table 5-67: WRITE (VBN Access) Output Fields 
Block Field Description 

RAB RFA Virtual block number (2 words) 
RAB STS Completion status code 
RAB STV Completion status value 
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Each major section of this chapter describes an RMS-11 control block, 
and includes: 

• Block summary table 

A table summarizes the entire control block. The table shows 
the offset, offset symbol, field size, and a brief description 
of each field in the block; for each mask or code for a 
field, the table shows the value, symbol, and a brief 
description of the mask or code. 

• Field summaries 

Each subsection following the block summary table is a 
description of one field in the block. A field that has masks 
that are very different in purpose (such as the FOP field in 
the FAB) is described as a number of separate "fields" (such 
as FOP FB$FID, FOP FB$RWO, and so forth) . 

The description of each field includes the following: 

USE: a summary of the purpose of the field 

SIZE: the size of the field 

INIT: the format of the field-initialization macro (if any) 

ACCESS: the formats of field-access macros to access the 
field 

MASKS or CODES: (if any) each mask or code symbol and a brief 
description 

INPUT: the operations that read values from the field, and 
the meanings of those values 

OUTPUT: the operations that store values in the field, and 
the meanings of those values 

Fields described as "Reserved" and undefined bits in masks should (and 
in some cases must) be 0. 
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6.1 ALL BLOCK SUMMARY 

This section summarizes the ALL block and its fields. Table 6-1 
summarizes the entire block, giving the offset, offset symbol, size, 
and a brief description for each field; for a field that has mask or 
code symbols, the table also gives the value, symbol, and a brief 
description for each mask or code. 



Table 6-1: ALL Block Summary 



Offset 



Offset Field 
Symbol Size 



Description 



000 0$C0D 1 byte 



001 0$BLN 1 byte 



002 


0$NXT 


1 


word 


004 


0$AID 


1 


byte 


005 


0$BKZ 


1 


byte 


006 


0$VOL 


1 


word 


010 


0$ALN 


1 


byte 



ALL block identifier code 

000004 XB$ALL ALL block identifier 

ALL block length (bytes) 

000034 XB$LAL ALL block length (bytes) 

Next XAB address 

Area number 

Area bucket size (blocks) 

Reserved 

Area alignment mask 

000002 XB$LBN Logical block alignment 
000004 XB$VBN Virtual block alignment 



011 0$AOP 1 byte Area option mask 



012 


0$ALQ 


2 


words 


012 


O$ALQ0 


1 


word 


014 


0$ALQ1 


1 


word 


016 


0$DEQ 


1 


word 


020 




1 


word 


022 


0$LOC 


2 


words 


022 


O$LOC0 


1 


word 


024 


0$L0C1 


1 


word 



000001 XB$HRD Hard area location 

000002 XB$CTG Contiguous area 

Area allocation size (blocks) 

ALQ field low word 

ALQ field high word 

Area default extension size (blocks) 

Reserved 

Area location 

LOC field low word 

LOC field high word 
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6.1.1 AID Field in ALL Block 



OSE 



Contains the area identifier for the area described by the 
ALL block. 



INIT X$AID number 

SIZE 1 byte 

ACCESS $FETCH dst,AID,reg 
$STORE src,AID,reg 
$COMPARE src,AID,reg 



;AID field to 1-byte dst 
;l-byte src to AID field 
;l-byte src with AID field 



INPUT 



CLOSE 

CREATE 

DISPLAY 

EXTEND 

OPEN 



Area number 
Area number 
Area number 
Area number 
Area number 
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6.1.2 ALN Field in ALL Block 



USE 

INIT 
SIZE 
ACCESS 



Indicates alignment for the area described by the ALL 
block. 

X$ALN mask 



1 byte 

$SET mask, ALN, reg 
$OFF mask, ALN, reg 



;Mask bits on in ALN field 
;Mask bits off in ALN field 



$TESTBITS mask, ALN, reg ;Test mask bits in ALN field 



$FETCH dst,ALN,reg 
$STORE src,ALN,reg 
$COMPARE src,ALN,reg 



;ALN field to 1-byte dst 
;l-byte src to ALN field 
;l-byte src with ALN field 



MASKS 



INPUT 



OUTPUT 



XB$LBN Logical block alignment 
XB$VBN Virtual block alignment 

CREATE Initial area alignment request 
EXTEND Area extension alignment request 

DISPLAY Area alignment mask (cleared) 
OPEN Area alignment mask (cleared) 
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6.1.3 ALQ Field in ALL Block 



USE 

INIT 
SIZE 
ACCESS 



INPUT 



OUTPUT 



Contains the allocation size for the area described by the 
ALL block. 

X$ALQ number 



2 words 

$FETCH dst,ALQ,reg 
$STORE src,ALQ,reg 
$FETCH dst,ALQn,reg 
$STORE src,ALQn,reg 
$COMPARE src,ALQn,reg 



;ALQ field to 2-word dst 
;2-word src to ALQ field 
;ALQ word n to 1-word dst 
; 1-word src to ALQ word n 
; 1-word src with ALQ word n 



CREATE 
EXTEND 



CREATE 
DISPLAY 
EXTEND 
OPEN 



Initial area allocation request size (blocks) 
Area allocation extension request size 
(blocks) 

Initial area allocation size (blocks) 

Unused area allocation size (blocks) 

Area allocation extension actual size (blocks) 

Unused area allocation size (blocks) 
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6.1.4 AOP Field in ALL Block (XB$CTG Mask) 



USE 



Indicates contiguity for the area described by the ALL 
block. 



INIT 
SIZE 
ACCESS 



INPUT 



OUTPUT 



X$AOP mask 

1 byte 

$SET mask, AOP, reg ;Mask bits on in AOP field 

$OFF mask, AOP, reg ;Mask bits off in AOP field 

$TESTBITS mask,AOP,reg ;Test mask bits in AOP field 

$FETCH dst,AOP,reg ;AOP field to 1-byte dst 

$STORE src,AOP,reg ;l-byte src to AOP field 

$COMPARE src, AOP, reg ;l-byte src with AOP field 

CREATE Contiguous area request 

EXTEND Contiguous area extension request 

DISPLAY Contiguous area (cleared) 
OPEN Contiguous area (cleared) 
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6.1.5 AOP Field in ALL Block (XB$HRD Mask) 



USE 
INIT 
SIZE 
ACCESS 



INPUT 



OUTPUT 



Indicates a demand for the requested location, 
X$AOP mask 



1 byte 

$SET mask, AOP, reg 
$OFF mask,AOP,reg 
$TESTBITS mask, AOP, reg 
$FETCH dst,AOP,reg 
$STORE src,AOP,reg 
$COMPARE src,AOP,reg 



;Mask bits on in AOP field 
;Mask bits off in AOP field 
;Test mask bits in AOP field 
;AOP field to 1-byte dst 
;l-byte src to AOP field 
;l-byte src with AOP field 



CREATE Area hard location request 

EXTEND Area extension hard location request 

DISPLAY Hard area location (cleared) 

OPEN Hard area location (cleared) 
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6.1.6 BKZ Field in ALL Block 



USE 

INIT 
SIZE 
ACCESS 

INPUT 
OUTPUT 



Contains the bucket size for the area described by the ALL 
block. 

X$BKZ number 

1 byte 



$FETCH dst,BKZ,reg 
$STORE src,BKZ,reg 
$COMPARE src,BKZ,reg 



;BKZ field to 1-byte dst 
;l-byte src to BKZ field 
; 1-byte src with BKZ field 



CREATE Area bucket size (blocks) 

DISPLAY Area bucket size (blocks) 
OPEN Area bucket size (blocks) 
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6.1.7 BLN Field in ALL Block (XB$LAL Code) 

DSE Contains the length of the ALL block. 

INIT None 

SIZE 1 byte 

ACCESS $FETCH dst,BLN,reg ;BLN field to 1-byte dst 

$COMPARE src,BLN,reg ; 1-byte src with BLN field 
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6.1.8 COD Field in ALL Block (XB$ALL Code) 

USE Contains the identifier for the ALL block. 

INIT None 

SIZE 1 byte 

ACCESS $FETCH dst,COD,reg ;COD field to 1-byte dst 

$COMPARE src,COD,reg ;l-byte src with COD field 
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6.1.9 DEQ Field in ALL Block 



USE 

INIT 
SIZE 
ACCESS 

INPUT 
OUTPUT 



Contains the default extension size for the area described 
by the ALL block. 

X$DEQ number 

1 word 



$FETCH dst,DEQ,reg 
$STORE src,DEQ,reg 
$COMPARE src,DEQ,reg 



DEQ field to 1-word dst 
1-word src to DEQ field 
1-word src with DEQ field 



CREATE Area default extension size (blocks) 

DISPLAY Area default extension size (blocks) 
OPEN Area default extension size (blocks) 



6-11 



CONTROL BLOCK FIELDS 
ALL BLOCK SUMMARY 



6.1.10 LOC Field in ALL Block 



USE Contains the location of the area described by the ALL 
block. 

The meaning of the location depends on the ALN mask: a 
logical block number (if XB$LBN) or a virtual block number 
(if XB$VBN) . 

INIT X$LOC number 

SIZE 2 words 

ACCESS $FETCH dst,LOC,reg ;LOC field to 2-word dst 

$STORE src,LOC,reg ;2-word src to LOC field 

$FETCH dst,LOCn,reg ;LOC word n to 1-word dst 

$STORE src,LOCn,reg ; 1-word src to LOC word n 

$C0MPARE src,LOCn,reg ; 1-word src with LOC word n 

INPUT CREATE Initial area location request 

EXTEND Area extension location request 
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6.1.11 NXT Field in ALL Block 



USE 



INIT 



SIZE 



ACCESS 



INPUT 



Contains the address of the next XAB (ALL, DAT, KEY, 
or SUM block) in a chain of XABs. 

X$NXT address 



PRO, 



1 word 

$FETCH dst,NXT,reg 
$STORE src,NXT,reg 
$COMPARE src,NXT,reg 



;NXT field to 1-word dst 
; 1-word src to NXT field 
; 1-word src with NXT field 



CLOSE Next XAB address 

CREATE Next XAB address 

DISPLAY Next XAB address 

ENTER Next XAB address 

ERASE Next XAB address 

EXTEND Next XAB address 

OPEN Next XAB address 

PARSE Next XAB address 

REMOVE Next XAB address 

RENAME Next XAB address 

SEARCH Next XAB address 
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6.2 DAT BLOCK SUMMARY 

This section summarizes the DAT block and its fields. Table 6-2 
summarizes the entire block, giving the offset, offset symbol, size, 
and a brief description for each field; for a field that has mask or 
code symbols, the table also gives the value, symbol, and a brief 
description for each mask or code. 



Table 6-2: DAT Block Summary 



Offset Field 
Offset Symbol Size 



Description 



000 0$COD 



001 0$BLN 



002 
004 
006 
016 
026 
036 



0$NXT 
0$RVN 
0$RDT 
0$CDT 
0$EDT 
0$BDT 



1 byte 
1 byte 



word 

word 

words 

words 

words 

words 



DAT block") identifi er code 

000003^-XB$DAT DAT block identifier 

DAT block length (bytes) 

000046 XB$DTL DAT block length (bytes) 

Next XAB address 
File revision number 
File revision date 
File creation date 
File expiration date 
Reserved 
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6.2.1 BLN Field in DAT Block (XB$DTL Code) 

USE Contains the length of the DAT block. 
INIT None 
SIZE 1 byte 

ACCESS $FETCH dst,BLN,reg ;BLN field to 1-byte dst 

$COMPARE src,BLN,reg ; 1-byte src with BLN field 
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6.2.2 CDT Field in DAT Block 



DSE Contains the binary creation date for the file. The time 
value is a binary number in 100-nanosecond units offset 
from the system base date and time, which is 00:00 
o^clock, November 17, 1858 (the Smithsonian base date and 
time for the astronomical calendar) . 

INIT None 

SIZE 4 words 

ACCESS $FETCH dst,CDT,reg ;CDT field to 4-word dst 

OUTPUT DISPLAY File creation date 
OPEN File creation date 
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6.2.3 COD Field in DAT Block (XB$DAT Code) 

USE Contains the identifier for the DAT block. 
INIT None 
SIZE 1 byte 

ACCESS $FETCH dst,COD,reg ;COD field to 1-byte dst 

$COMPARE src,COD,reg ; 1-byte src with COD field 
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6.2.4 EDT Field in DAT Block 



USE Contains the expiration date for the file. The time value 
is a binary number in 100-nanosecond units offset from the 
system base date and time, which is 00:00 o'clock, 
November 17, 1858 (the Smithsonian base date and time for 
the astronomical calendar) . 

INIT None 

SIZE 4 words 

ACCESS $FETCH dst,EDT,reg ;EDT field to 4-word dst 

OUTPUT OPEN File expiration date 
DISPLAY File expiration date 
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6.2.5 NXT Field in DAT Block 



USE 



Contains the address of the next XAB (ALL, DAT, KEY, 
or SUM block) in a chain of XABs . 



PRO, 



INIT 



SIZE 



ACCESS 



INPUT 



X$NXT address 

1 word 

$FETCH dst,NXT,reg 
$STORE src,NXT,reg 
$COMPARE src,NXT,reg 



;NXT field to 1-word dst 
; 1-word src to NXT field 
; 1-word src with NXT field 



CLOSE Next XAB address 

CREATE Next XAB address 

DISPLAY Next XAB address 

ENTER Next XAB address 

ERASE Next XAB address 

EXTEND Next XAB address 

OPEN Next XAB address 

PARSE Next XAB address 

REMOVE Next XAB address 

RENAME Next XAB address 

SEARCH Next XAB address 
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6.2.6 RDT Field in DAT Block 



DSE Contains the binary revision date for the file. The time 
value is a binary number in 100-nanosecond units offset 
from the system base date and time, which is 00:00 
o'clock, November 17, 1858 (the Smithsonian base date and 
time for the astronomical calendar) . 

INIT None 

SIZE 4 words 

ACCESS $FETCH dst,RDT,reg ;RDT field to 4-word dst 

OUTPUT DISPLAY File revision date 
OPEN File revision date 
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6.2.7 RVN Field in DAT Block 



USE 



Contains the revision number (number of times closed) for 
the file. 



INIT 
SIZE 
ACCESS 

ODTPDT 



None 

1 word 

$FETCH dst,RVN,reg 
$COMPARE src,RVN,reg 



;RVN field to 1-word dst 
; 1-word src with RVN field 



DISPLAY File revision number 
OPEN File revision number 
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6.3 FAB SUMMARY 



This section summarizes the FAB and its fields. Table 6-3 summarizes 
the entire block, giving the offset, offset symbol, size, and a brief 
description for each field; for a field that has mask or code 
symbols, the table also gives the value, symbol, and a brief 
description for each mask or code. 



Table 6-3: FAB Summary 



Offset Field 
Offset Symbol Size 



Description 



000 0$BID 1 byte 



001 0$BLN 1 byte 



002 
004 
006 
010 
012 
016 
020 



0$CTX 
0$IFI 
0$STS 
0$STV 
0$ALQ 
0$DEQ 
0$FAC 



word 

word 

word 

word 

words 

word 

byte 



FAB identifier 

000003 FB$BID FAB identification code 
FAB length (bytes) 

000120 FB$BLN FAB length (bytes) 

User context 

Internal file identifier 

Completion status code 

Completion status value 

File allocation size (blocks) 

File default extension size (blocks) 

Requested access mask 

000001 FB$PUT Request put access 

000002 FB$GET Request find/get access 

000004 FB$DEL Request find/get/delete 

access 
000010 FB$UPD Request find/get/update 

access 
000020 FB$TRN Request find/get/truncate 

access 

000041 FB$WRT Request block write 

access 

000042 FB$REA Request block read access 



021 0$SHR 1 byte Shared access mask 



000002 FB$GET Share find/get access 
000015 FB$WRI Share find/get/put/update/ 

delete access 
000040 FB$UPI Share any access 

(user-provided interlock) 
000100 FB$NIL No access sharing 



(Continued on next page) 
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Table 6-3 (Cont.): FAB Summary 



Offset Field 
Offset Symbol Size 



022 



0$FOP 1 word 



024 
025 



0$RTV 
0$ORG 



1 byte 
1 byte 



026 



0$RAT 1 byte 



Description 



File processing option mask 

000001 FB$RWO Rewind magtape before 

operation 

000002 FB$RWC Rewind magtape after 

closing file 
000010 FB$POS Position magtape after 

last-closed file 
000020 FB$DLK No file locking on 

abnormal close 
000200 FB$CTG Contiguous file 
000400 FB$SUP Supersede existing file 
001000 FB$NEF No end-of-file magtape 

positioning 
002000 FB$TMP Temporary file 
004000 FB$MKD Mark file for deletion 
006000 FB$TMD Temporary file, mark for 

deletion 
010000 FB$FID Use information in NAM 

block 
020000 FB$DFW Defer writing 



Retrieval pointer count 
File organization code 



FB$SEQ Sequential file 

organization 
FB$REL Relative file 

organization 
FB$IDX Indexed file organization 



000000 
000020 
000040 
Record handling mask 



000001 FB$FTN FORTRAN-Style 

carriage-control 
character in record 

000002 FB$CR Add CRLF to print record 

(LF-record-CR) 
000004 FB$PRN VFC print record handling 
000010 FB$BLK Blocked records 



027 



0$RFM 1 byte Record format code 



000000 FB$UDF Undefined record format 

000001 FB$FIX Fixed-length record 

format 

000002 FB$VAR Variable-length record 

format 

000003 FB$VFC VFC record format 

000004 FB$STM Stream record format 



(Continued on next page) 
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Table 6-3 (Cont.)s FAB Summary 



Offset 



Offset 
Symbol 



Field 
Size 



Description 



030 0$XAB 1 word XAB address 

032 0$BPA 1 word Private buffer pool address 

034 0$BPS 1 word Private buffer pool size (bytes) 

036 0$MRS 1 word Maximum record size (bytes) 

040 0$MRN 2 words Maximum record number 

044 0$LRL 1 word Longest record length 

046 0$NAM 1 word NAM block address 

050 0$FNA 1 word File string address 

052 0$DNA 1 word Default string address 

054 0$FNS 1 byte File string size (bytes) 

055 0$DNS 1 byte Default string size (bytes) 

056 0$BLS 1 word Magtape block size (characters) 

060 0$FSZ 1 byte Fixed control area size for VFC records 

(bytes) 

061 0$BKS 1 byte File bucket size (blocks) 

062 0$DEV 1 byte Device characteristic mask 

000001 FB$REC Record-oriented device 

000002 FB$CCL Carriage-control device 
000004 FB$TRM Terminal device 
000010 FB$MDI Multidirectory device 
000020 FB$SDI Single-directory device 
000040 FB$SQD Sequential device 

063 0$LCH 1 byte Logical channel number 
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USE 
INIT 
SIZE 
ACCESS 



INPUT 



OUTPUT 



Contains the allocation size for the file. 
F$ALQ number 



2 words 

$FETCH dst,ALQ,reg 
$STORE src,ALQ,reg 
$FETCH dst,ALQn,reg 
$STORE src,ALQn,reg 
$COMPARE src,ALQn,reg 



;ALQ field to 2-word dst 
; 2-word src to ALQ field 
;ALQ word n to 1-word dst 
; 1-word src to ALQ word n 
; 1-word src with ALQ word n 



CREATE 
EXTEND 



CREATE 
EXTEND 
OPEN 



Initial file allocation request size (blocks) 
File allocation extension request size 
(blocks) 

Initial file allocation size (blocks) 

File allocation extension actual size (blocks) 

Current file allocation (blocks) 
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6.3.2 BID Field in FAB (FB$BID Code) 

OSE Contains the identifier for the FAB. 

INIT None 

SIZE 1 byte 

ACCESS $FETCH dst,BID,reg ;BID field to 1-byte dst 

$COMPARE src,BID,reg ;l-byte src with BID field 



6-26 



CONTROL BLOCK FIELDS 
FAB SUMMARY 



6.3.3 BKS Field in FAB 



USE 
INIT 
SIZE 
ACCESS 

INPUT 
OUTPUT 



Contains the bucket size for the file. 
F$BKS number 
1 byte 

$FETCH dst,BKS,reg ;BKS field to 1-byte dst 
$STORE src,BKS,reg ;l-byte src to BKS field 
$COMPARE src,BKS,reg ; 1-byte src with BKS field 

CREATE File bucket size (blocks) 

OPEN File bucket size (blocks) 
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6.3.4 BLN Field in FAB (FB$BLN Code) 

USE Contains the length of the FAB. 

INIT None 

SIZE 1 byte 

ACCESS $FETCH dst,BLN,reg ;BLN field to 1-byte dst 

$COMPARE src,BLN,reg ;l-byte src with BLN field 
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6.3.5 BLS Field in FAB 



USE 
INIT 
SIZE 
ACCESS 

INPUT 
OUTPUT 



Contains the magtape block size for the file. 
F$BLS number 



1 word 

$FETCH dst,BLS,reg 
$STORE src,BLS,reg 
$COMPARE src,BLS,reg 



;BLS field to 1-word dst 
; 1-word src to BLS field 
;l-word src with BLS field 



CREATE Magtape block size (characters) 
OPEN Magtape block size (characters) 
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6.3.6 BPA Field in FAB 



USE 

INIT 
SIZE 
ACCESS 



Contains the address of the private buffer pool for the 
operation. 

F$BPA address 

1 word 



$FETCH dst,BPA,reg 
$STORE src,BPA,reg 
$COMPARE src,BPA,reg 



;BPA field to 1-word dst 
; 1-word src to BPA field 
;l-word src with BPA field 



INPUT 


CREATE 


Private 


buffer 


pool 


address 




ENTER 


Private 


buffer 


pool 


address 




ERASE 


Private 


buffer 


pool 


address 




OPEN 


Private 


buffer 


pool 


address 




PARSE 


Private 


buffer 


pool 


address 




REMOVE 


Private 


buffer 


pool 


address 




RENAME 


Private 


buffer 


pool 


address 




SEARCH 


Private 


buffer 


pool 


address 


OUTPUT 


CLOSE 


Private 


buffer 


pool 


address 



6-30 



CONTROL BLOCK FIELDS 
FAB SUMMARY 



6.3.7 BPS Field in FAB 



USE 

INIT 
SIZE 
ACCESS 



Contains the size of the private buffer pool for the 
operation. 

F$BPS number 



1 word 

$FETCH dst,BPS,reg 
$STORE src,BPS,reg 
$COMPARE src,BPS,reg 



;BPS field to 1-word dst 
;l-word src to BPS field 
; 1-word src with BPS field 



INPUT 


CREATE 


Private 


buffer 


pool 


si ze 


(bytes) 




ENTER 


Private 


buffer 


pool 


size 


(bytes) 




ERASE 


Private 


buffer 


pool 


size 


(bytes) 




OPEN 


Private 


buffer 


pool 


size 


(bytes) 




PARSE 


Private 


buffer 


pool 


size 


(bytes) 




REMOVE 


Private 


buffer 


pool 


size 


(bytes) 




RENAME 


Private 


buffer 


pool 


size 


(bytes) 




SEARCH 


Private 


buffer 


pool 


size 


(bytes) 


OUTPUT 


CLOSE 


Private 


buffer 


pool 


size 


(bytes) 
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6.3.8 CTX Field in FAB 



USE Contains any information you may want to associate with 
the file at run time. 

INIT F$CTX number 

SIZE 1 word 

ACCESS $FETCH dst,CTX,reg ;CTX field to 1-word dst 
$STORE src,CTX,reg ;l-word src to CTX field 
$COMPARE src,CTX,reg ;l-word src with CTX field 
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6.3.9 DEQ Field in FAB 



USE 
INIT 
SIZE 
ACCESS 



Contains the default extension size for the file, 
F$DEQ number 
1 word 



$FETCH dst f DEQ,reg 
$STORE src,DEQ,reg 
$COMPARE src,DEQ,reg 



;DEQ field to 1-word dst 
; 1-word src to DEQ field 
;l-word src with DEQ field 



INPUT 


CREATE 




OPEN 


OUTPUT 


OPEN 



Permanent file default extension size (blocks) 
While-open file default extension size 
(blocks) 

Current file default extension size (blocks) 
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6.3.10 DEV Field in FAB 



USE 
INIT 
SIZE 
ACCESS 

MASKS 



OUTPUT 



Indicates device characteristics for the file. 

None 

1 byte 

$TESTBITS mask, DEV, reg ;Test mask bits in DEV field 
$FETCH dst,DEV,reg ;DEV field to 1-byte dst 
$COMPARE src,DEV,reg ; 1-byte src with DEV field 



FB$CCL 
FB$MDI 
FB$REC 
FB$SDI 
FB$SQD 
FB$TRM 

CREATE 

ENTER 

ERASE 

OPEN 

PARSE 

REMOVE 

RENAME 

SEARCH 



Carriage-control device 
Multidirectory device 
Record-oriented device 
Single-directory device 
Sequential device 
Terminal device 



Device 
Device 
Device 
Device 
Device 
Device 
Device 
Device 



char 
char 
char 
char 
char 
char 
char 
char 



acteri 
acteri 
acteri 
acteri 
acteri 
acteri 
acteri 
acteri 



stic 
stic 
stic 
stic 
stic 
stic 
stic 
stic 



mask 
mask 
mask 
mask 
mask 
mask 
mask 
mask 
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USE 

INIT 
SIZE 
ACCESS 

INPUT 



Contains the address of the default string for the 
operation. 

F$DNA address 



1 word 

$FETCH dst,DNA,reg 
$STORE src,DNA,reg 
$COMPARE src,DNA,reg 



;DNA field to 1-word dst 
; 1-word src to DNA field 
;l-word src with DNA field 



CREATE 

ENTER 

ERASE 

OPEN 

PARSE 

REMOVE 

RENAME 



Default 
Default 
Default 
Default 
Default 
Default 
Default 



string 
string 
string 
string 
string 
string 
string 



address 
address 
address 
address 
address 
address 
address 
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6.3.12 DNS Field in FAB 



USE Contains the size of the default string for the operation, 

INIT F$DNS number 

SIZE 1 byte 

ACCESS $FETCH dst,DNS,reg ;DNS field to 1-byte dst 

$STORE src f DNS,reg ;l-byte src to DNS field 
$COMPARE src,DNS,reg ;l-byte src with DNS field 

INPUT CREATE Default string size (bytes) 

ENTER Default string size (bytes) 

ERASE Default string size (bytes) 

OPEN Default string size (bytes) 

PARSE Default string size (bytes) 

REMOVE Default string size (bytes) 

RENAME Default string size (bytes) 
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6.3.13 FAC Field in FAB 



USE 
INIT 
SIZE 
ACCESS 



MASKS 



INPUT 



Indicates the requested access for the file, 
F$FAC mask 



1 byte 

$SET mask, FAC, reg 
$OFF mask, FAC, reg 
$TESTBITS mask, FAC, reg 
$FETCH dst,FAC,reg 
$STORE src,FAC,reg 
$COMPARE s re, FAC, reg 



;Mask bits on in FAC field 
;Mask bits off in FAC field 
;Test mask bits in FAC field 
;FAC field to 1-byte dst 
;l-byte sre to FAC field 
; 1-byte sre with FAC field 



FB$DEL Request find/get/delete access 

FB$GET Request find/get access 

FB$PUT Request put access 

FB$REA Request block read access 

FB$TRN Request find/get/truncate access 

FB$UPD Request find/get/update access 

FB$WRT Request block write access 

CREATE Requested access mask 
OPEN Requested access mask 
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6.3.14 FNA Field in FAB 

USE Contains the address of the file string for the file. 

INIT F$FNA address 

SIZE 1 word 

ACCESS $FETCH dst,FNA,reg ;FNA field to 1-word dst 
$STORE src,FNA,reg ;l-word src to FNA field 
$COMPARE src,FNA,reg ;l-word src with FNA field 

INPUT CREATE File string address 

ENTER File string address 

ERASE File string address 

OPEN File string address 

PARSE File string address 

REMOVE File string address 

RENAME File string address 
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6.3.15 FNS Field in FAB 



USE 



INIT 



Contains the size of the file string for the file, 
F$FNS number 



SIZE 



ACCESS 



INPUT 



1 byte 

$FETCH dst,FNS,reg 
$STORE src,FNS,reg 
$COMPARE src f FNS,reg 



;FNS field to 1-byte dst 
; 1-byte src to FNS field 
; 1-byte src with FNS field 



CREATE File string size (bytes) 

ENTER File string size (bytes) 

ERASE File string size (bytes) 

OPEN File string size (bytes) 

PARSE File string size (bytes) 

REMOVE File string size (bytes) 

RENAME File string size (bytes) 
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6.3.16 FOP Field in FAB (FB$CTG Mask) 



USE 
INIT 
SIZE 
ACCESS 



INPUT 



OUTPUT 



Indicates file contiguity. 

F$FOP mask 

1 word 

$SET mask, FOP, reg ;Mask bits on in FOP field 

$OFF mask, FOP, reg ;Mask bits off in FOP field 

$TESTBITS mask, FOP, reg ;Test mask bits in FOP field 

$FETCH dst,FOP,reg ;FOP field to 1-word dst 

$STORE src, FOP, reg ; 1-word src to FOP field 

$COMPARE src, FOP, reg ;l-word src with FOP field 

CREATE Contiguous file request 

EXTEND Contiguous file extension request 

OPEN Contiguous file 
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USE 
INIT 
SIZE 
ACCESS 



Requests deferred writing for the file. 
F$FOP mask 



1 word 

$SET mask, FOP, reg 
$OFF mask, FOP, reg 
$TESTBITS mask, FOP, reg 
$FETCH dst,FOP,reg 
$STORE src,FOP,reg 
$COMPARE src,FOP,reg 



;Mask bits on in FOP field 
;Mask bits off in FOP field 
;Test mask bits in FOP field 
;FOP field to 1-word dst 
; 1-word src to FOP field 
;l-word src with FOP field 



INPUT 



CREATE 
OPEN 



Defer writing 
Defer writing 
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6.3.18 FOP Field in FAB (FB$DLK Mask) 



USE Requests no file locking if the file is closed abnormally. 

INIT F$FOP mask 

SIZE 1 word 

ACCESS $SET mask, FOP, reg ;Mask bits on in FOP field 

$OFF mask, FOP, reg ;Mask bits off in FOP field 

$TESTBITS mask, FOP, reg ;Test mask bits in FOP field 

$FETCH dst,FOP,reg ;FOP field to 1-word dst 

$STORE src,FOP,reg ;l-word src to FOP field 

$COMPARE src, FOP, reg ;l-word src with FOP field 

INPUT CREATE No file locking on abnormal close 
OPEN No file locking on abnormal close 
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6.3.19 FOP Field in FAB (FB$FID Mask) 



USE 



Requests that NAM block information be used to identify 
the file. 



INIT 
SIZE 
ACCESS 



INPUT 



F$FOP mask 

1 word 

$SET mask, FOP, reg ;Mask bits on in FOP field 

$OFF mask, FOP, reg ;Mask bits off in FOP field 

$TESTBITS mask,FOP,reg ;Test mask bits in FOP field 

$FETCH dst,FOP,reg ;FOP field to 1-word dst 

$STORE src,FOP,reg ; 1-word src to FOP field 

$COMPARE src, FOP, reg ; 1-word src with FOP field 

CREATE Use information in NAM block 

ENTER Use information in NAM block 

ERASE Use information in NAM block 

OPEN Use information in NAM block 

REMOVE Use information in NAM block 

RENAME Use information in NAM block 
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6.3.20 FOP Field in FAB (FB$MKD Mask) 



OSE 
INIT 
SIZE 
ACCESS 



Requests that the file be marked for deletion. 

F$FOP mask 

1 word 

$SET mask, FOP, reg ;Mask bits on in FOP field 

$OFF mask, FOP, reg ;Mask bits off in FOP field 

$TESTBITS mask, FOP, reg ;Test mask bits in FOP field 

$FETCH dst,FOP,reg ;FOP field to 1-word dst 

$STORE src,FOP,reg ;l-word src to FOP field 

$COMPARE src, FOP, reg ; 1-word src with FOP field 



INPUT 



CREATE 



Mark file for deletion 
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6.3.21 FOP Field in FAB (FB$NEF Mask) 



USE 

INIT 
SIZE 
ACCESS 



Requests that the magtape file be positioned to the 
beginning of the file. 

F$FOP mask 



1 word 

$SET mask, FOP, reg 
$OFF mask, FOP, reg 
$TESTBITS mask, FOP, reg 
$FETCH dst,FOP,reg 
$STORE src,FOP,reg 
$COMPARE src,FOP,reg 



;Mask bits on in FOP field 
;Mask bits off in FOP field 
;Test mask bits in FOP field 
;FOP field to 1-word dst 
; 1-word src to FOP field 
;l-word src with FOP field 



INPUT 



OPEN 



No end-of-file magtape positioning 
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6.3.22 FOP Field in FAB (FB$POS Mask) 



USE Requests that the magtape be positioned to the end of the 
last-closed file before creating the new file. 

INIT F$FOP mask 

SIZE 1 word 

ACCESS $SET mask, FOP, reg ;Mask bits on in FOP field 

$OFF mask, FOP, reg ;Mask bits off in FOP field 

$TESTBITS mask, FOP, reg ;Test mask bits in FOP field 

$FETCH dst,FOP,reg ;FOP field to 1-word dst 

$STORE src,FOP,reg ; 1-word src to FOP field 

$COMPARE src, FOP, reg ;l-word src with FOP field 

INPUT CREATE Position magtape after last-closed file 
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USE 

INIT 
SIZE 
ACCESS 



INPUT 



Requests that the magtape be rewound when the file is 
closed. 

F$FOP mask 

1 word 

$SET mask, FOP, reg ;Mask bits on in FOP field 

$OFF mask, FOP, reg ;Mask bits off in FOP field 

$TESTBITS mask, FOP, reg ;Test mask bits in FOP field 

$FETCH dst,FOP,reg ;FOP field to 1-word dst 

$STORE src,FOP,reg ;l-word sre to FOP field 

$COMPARE src,FOP,reg ; 1-word src with FOP field 

CLOSE Rewind magtape after closing file 

CREATE Rewind magtape after closing file 

OPEN Rewind magtape after closing file 

SEARCH Rewind magtape after closing file 
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6.3.24 FOP Field in FAB (FB$RWO Mask) 



USE 
INIT 
SIZE 
ACCESS 



Requests that the magtape be rewound before the operation, 
F$FOP mask 
1 word 



$SET mask, FOP, reg 
$OFF mask, FOP, reg 
$TESTBITS mask, FOP, reg 
$FETCH dst,FOP,reg 
$STORE src,FOP,reg 
$COMPARE src,FOP,reg 



;Mask bits on in FOP field 
;Mask bits off in FOP field 
;Test mask bits in FOP field 
;FOP field to 1-word dst 
; 1-word src to FOP field 
; 1-word src with FOP field 



INPUT 



CREATE Rewind magtape before creating file 
OPEN Rewind magtape before searching for file 
SEARCH Rewind magtape before operation 
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6.3.25 FOP Field in FAB (FB$SOP Mask) 



USE 

INIT 
SIZE 
ACCESS 



Requests that the created file supersede the old file with 

the same specification (if one exists) . 

F$FOP mask 

1 word 

$SET mask, FOP, reg ;Mask bits on in FOP field 

$OFF mask, FOP, reg ;Mask bits off in FOP field 

$TESTBITS mask, FOP, reg ;Test mask bits in FOP field 

$FETCH dst,FOP,reg ;FOP field to 1-word dst 

$STORE src,FOP,reg ; 1-word src to FOP field 

$COMPARE src, FOP, reg ;l-word src with FOP field 



INPUT 



CREATE 



Supersede existing file 
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6.3.26 FOP Field in FAB (FB$TMP Mask) 



USE Requests that the created file be a temporary file (one 
with no directory entry). 

INIT F$FOP mask 

SIZE 1 word 

ACCESS $SET mask, FOP, reg ;Mask bits on in FOP field 

$OFF mask, FOP, reg ;Mask bits off in FOP field 

$TESTBITS mask, FOP, reg ;Test mask bits in FOP field 

$FETCH dst,FOP,reg ;FOP field to 1-word dst 

$STORE src,FOP,reg ; 1-word src to FOP field 

$COMPARE src,FOP,reg ;l-word src with FOP field 

INPUT CREATE Temporary file 
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USE 

INIT 
SIZE 
ACCESS 

IN POT 
ODTPDT 



Contains the size of the fixed control area for VFC 
records. 

F$FSZ number 

1 byte 



$FETCH dst,FSZ,reg 
$STORE src,FSZ,reg 
$COMPARE src,FSZ,reg 



;FSZ field to 1-byte dst 
;l-byte src to FSZ field 
; 1-byte src with FSZ field 



CREATE Fixed control area size for VFC 
(bytes) 

OPEN Fixed control area size for VFC 
(bytes) 



records 



records 
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6.3.28 IFI Field in FAB 



USE 
INIT 
SIZE 
ACCESS 

INPUT 
OUTPUT 



Contains the internal file identifier for the file, 
None 



1 word 

$FETCH dst,IFI,reg 
$COMPARE src,IFI,reg 



;IFI field to 1-word dst 
;l-word src with IFI field 



CLOSE Internal file identifier 

CONNECT Internal file identifier 

DISPLAY Internal file identifier 

EXTEND Internal file identifier 

CLOSE Internal file identifier 

CREATE Internal file identifier 

OPEN Internal file identifier 
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USE 
INIT 
SIZE 
ACCESS 

INPUT 



Contains the logical channel number for the operation, 
F$LCH number 



1 byte 

$FETCH dst,LCH,reg 
$STORE src,LCH,reg 
$COMPARE src,LCH,reg 



;LCH field to 1-byte dst 
;l-byte src to LCH field 
; 1-byte src with LCH field 



CREATE 

ENTER 

ERASE 

OPEN 

PARSE 

REMOVE 

RENAME 

SEARCH 



Logical 
Logical 
Logical 
Logical 
Logical 
Logical 
Logical 
Logical 



channel 
channel 
channel 
channel 
channel 
channel 
channel 
channel 



number 
number 
number 
number 
number 
number 
number 
number 



6-53 



CONTROL BLOCK FIELDS 
FAB SUMMARY 



6.3.30 LRL Field in FAB 



USE 

INIT 
SIZE 
ACCESS 

INPUT 

OUTPUT 



Contains the length of the longest record in a sequential 
file. 

None 

1 word 

$FETCH dst,LRL,reg ;LRL field to 1-word dst 
$COMPARE src,LRL,reg ;l-word src with LRL field 

CREATE Longest record length (block access to 
sequential files only) 



OPEN 



Longest record length 



6-54 



CONTROL BLOCK FIELDS 
FAB SUMMARY 



6.3.31 MRN Field in FAB 



USE 

INIT 
SIZE 
ACCESS 



INPUT 
OUTPUT 



Contains the maximum record number allowed in 
file. 

F$MRN number 



relative 



2 words 

$FETCH dst,MRN,reg 
$STORE src,MRN,reg 
$FETCH dst,MRNn,reg 
$STORE src,MRNn,reg 
$COMPARE src,MRNn,reg 



;MRN field to 2-word dst 
; 2-word src to MRN field 
;MRN word n to 1-word dst 
; 1-word src to MRN word n 
; 1-word src with MRN word n 



CREATE 



OPEN 



Maximum record number 
Maximum record number 
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6.3.32 MRS Field in FAB 



OSE Contains the record size for fixed-length records or 
maximum record size for other format records for the file. 

INIT F$MRS number 

SIZE 1 word 

ACCESS $FETCH dst,MRS f reg ;MRS field to 1-word dst 
$STORE src,MRS,reg ;l-word src to MRS field 
$COMPARE src,MRS,reg ;l-word src with MRS field 

INPUT CREATE Maximum record size (bytes) 

OUTPUT OPEN Maximum record size (bytes) 
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6.3.33 NAM Field in FAB 



USE 



INIT 



Contains the address of the NAM block for the operation, 



F$NAM address 



SIZE 



ACCESS 



INPUT 



1 word 

$FETCH dst,NAM,reg 
$STORE src,NAM,reg 
$COMPARE src,NAM,reg 



;NAM field to 1-word dst 
; 1-word src to NAM field 
; 1-word src with NAM field 



CREATE NAM block address 

ENTER NAM block address 

ERASE NAM block address 

OPEN NAM block address 

PARSE NAM block address 

REMOVE NAM block address 

RENAME NAM block address 

SEARCH NAM block address 
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6.3.34 ORG Field in FAB 



USE 
INIT 
SIZE 
ACCESS 

CODES 

INPUT 
OUTPUT 



Contains the file organization code. 
F$ORG code 



1 byte 

$FETCH dst,ORG,reg 
$STORE src,ORG,reg 
$COMPARE src,ORG,reg 



;ORG field to 1-byte dst 
;l-byte src to ORG field 
; 1-byte src with ORG field 



FB$IDX Indexed file organization 

FB$REL Relative file organization 

FB$SEQ Sequential file organization 

CREATE File organization code 

OPEN File organization code 
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USE 

INIT 
SIZE 
ACCESS 



MASKS 

INPUT 
OUTPUT 



Indicates the record-output characteristic for the file. 
(The RAT field also contains the record-blocking 
characteristic, which is described in the next section.) 

F$RAT mask 

1 byte 

$SET mask, RAT, reg ;Mask bits on in RAT field 

$OFF mask, RAT, reg ;Mask bits off in RAT field 

$TESTBITS mask, RAT, reg ;Test mask bits in RAT field 

$FETCH dst,RAT,reg ;RAT field to 1-byte dst 

$STORE src,RAT,reg ; 1-byte src to RAT field 

$COMPARE src, RAT, reg ;l-byte src with RAT field 

FB$CR Add CRLF to print record (LF-record-CR) 

FB$FTN FORTRAN-style carriage-control character in record 

FB$PRN VFC print record handling 



CREATE 



OPEN 



Record handling mask 
Record handling mask 
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6.3.36 RAT Field in FAB (FB$BLK Mask) 



USE 

INIT 
SIZE 
ACCESS 



INPUT 
OUTPUT 



Indicates whether the file has blocked records. (The RAT 
field also contains the record-output characteristic, 
which is described in the previous section.) 

F$RAT mask 



1 byte 

$SET mask, RAT, reg 
$OFF mask, RAT, reg 
$TESTBITS mask, RAT, reg 
$FETCH dst,RAT,reg 
$STORE src,RAT,reg 
$COMPARE src,RAT,reg 



;Mask bits on in RAT field 
;Mask bits off in RAT field 
;Test mask bits in RAT field 
;RAT field to 1-byte dst 
;l-byte src to RAT field 
;l-byte src with RAT field 



CREATE 



OPEN 



Blocked records 



Blocked records 
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6.3.37 RFM Field in FAB 



USE 
INIT 
SIZE 
ACCESS 

CODES 



INPUT 
OUTPUT 



Contains the record format code for the file, 
F$RFM code 



1 byte 

$FETCH dst,RFM,reg 
$STORE src,RFM,reg 
$COMPARE src,RFM,reg 



RFM field to 1-byte dst 
1-byte src to RFM field 
1-byte src with RFM field 



FB$FIX Fixed-length record format 

FB$STM Stream record format 

FB$UDF Undefined record format 

FB$VAR Variable-length record format 

FB$VFC VFC record format 

CREATE Record format code 

OPEN Record format code 
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6.3.38 RTV Field in FAB 



USE Contains the retrieval pointer count for the file, 

INIT F$RTV number 

SIZE 1 byte 

ACCESS $FETCH dst,RTV,reg ;RTV field to 1-byte dst 
$STORE src,RTV,reg ;l-byte src to RTV field 
$COMPARE src,RTV f reg ;l-byte src with RTV field 

INPDT CREATE Retrieval pointer count 
OPEN Retrieval pointer count 



6-62 



CONTROL BLOCK FIELDS 
FAB SUMMARY 



6.3.39 SHR Field in FAB 



USE Indicates requested access sharing for the file. 

INIT F$SHR mask 



SIZE 



ACCESS 



1 byte 

$SET mask, SHR, reg 
$OFF mask, SHR, reg 
$TESTBITS mask,SHR,reg 
$FETCH dst,SHR,reg 
$STORE src,SHR,reg 
$COMPARE src,SHR,reg 



;Mask bits on in SHR field 
;Mask bits off in SHR field 
;Test mask bits in SHR field 
;SHR field to 1-byte dst 
;l-byte src to SHR field 
;l-byte src with SHR field 



MASKS 



INPUT 



FB$GET Share find/get access 

FB$NIL No access sharing 

FB$UPI Share any access (user-provided interlock) 

FB$WRI Share find/get/put/update/delete access 

CREATE Shared access mask 
OPEN Shared access mask 
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6.3.40 STS Field in FAB 



USE Contains the completion status code for the operation, 

INIT None 

SIZE 1 word 

ACCESS $FETCH dst,STS,reg ;STS field to 1-word dst 

$COMPARE src,STS,reg ;l-word src with STS field 

OUTPUT CLOSE Completion status code 

CREATE Completion status code 

DISPLAY Completion status code 

ENTER Completion status code 

ERASE Completion status code 

EXTEND Completion status code 

OPEN Completion status code 

PARSE Completion status code 

REMOVE Completion status code 

RENAME Completion status code 

SEARCH Completion status code 
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USE Contains the completion status value for the operation, 
INIT None 



SIZE 



ACCESS 



OUTPUT 



1 word 

$FETCH dst,STV,reg 
$COMPARE src,STV,reg 



;STV field to 1-word dst 
;l-word src with STV field 



CLOSE Completion status value 

CREATE Completion status value 

DISPLAY Completion status value 

ENTER Completion status value 

ERASE Completion status value 

EXTEND Completion status value 

OPEN Completion status value 

PARSE Completion status value 

REMOVE Completion status value 

RENAME Completion status value 

SEARCH Completion status value 
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6.3.42 XAB Field in FAB 



DSE Contains the address of the first XAB (ALL, DAT, KEY, PRO, 
or SUM block) in a chain of XABs. 

INIT F$XAB address 

SIZE 1 word 

ACCESS $FETCH dst,XAB,reg ;XAB field to 1-word dst 
$STORE src,XAB,reg ;l-word src to XAB field 
$COMPARE src,XAB,reg ; 1-word src with XAB field 

INPUT CLOSE XAB address 

CREATE XAB address 

DISPLAY XAB address 

EXTEND XAB address 

OPEN XAB address 
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6.4 KEY BLOCK SUMMARY 

This section summarizes the KEY block and its fields. Table 6-4 
summarizes the entire block, giving the offset, offset symbol, size, 
and a brief description for each field; for a field that has mask or 
code symbols, the table also gives the value, symbol, and a brief 
description for each mask or code. 



Table 6-4: KEY Block Summary 



Offset Field 
Offset Symbol Size 



Description 



000 0$COD 1 byte 



001 0$BLN 1 byte 



002 


0$NXT 


1 


word 


004 


0$REF 


1 


byte 


005 


0$LVL 


1 


byte 


006 


0$IFL 


1 


word 


010 


0$DFL 


1 


word 


012 


0$NUL 


1 


byte 


013 


0$IAN 


1 


byte 


014 


0$LAN 


1 


byte 


015 


0$DAN 


1 


byte 


016 


0$FLG 


1 


byte 



KEY block identifier code 

000001 XB$KEY KEY block identifier 

KEY block length (bytes) 

000070 XB$KYL KEY block length (bytes) 

Next XAB address 

Index reference number 

Number of index levels (not including 

data level) 

Index bucket fill factor 

Data bucket fill factor 

Null key character 

Higher level index area number 

Lowest index level area number 

Data area number 

Index option mask 

000001 XB$DUP Duplicate record keys 

allowed 

000002 XB$CHG Record key changes 

allowed on update 
000020 XB$INI No entries yet made in 

index 
000004 XB$NUL Null record keys not 

indexed 



017 0$DTP 1 byte Key data type code 

000000 XB$STG String 



000001 XB$IN2 15-bit signed integer 

000002 XB$BN2 16-bit unsigned integer 

000003 XB$IN4 31-bit signed integer 

000004 XB$BN4 32-bit unsigned integer 

000005 XB$PAC Packed decimal number 



(Continued on next page) 
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Table 6-4 (Cont.): KEY Block Summary 



Offset 



Offset Field 
Symbol Size 



Description 



020 
022 
022 
024 
026 
030 
032 
034 
036 
040 
042 
042 
043 
044 
045 
046 
047 
050 
051 
052 
056 
062 
063 
064 
065 



0$KNM 

0$POS 

O$POS0 

0$POSl 

0$POS2 

0$POS3 

0$POS4 

0$POS5 

0$POS6 

0$POS7 

0$SIZ 

O$SIZ0 

0$SIZ1 

0$SIZ2 

0$SIZ3 

0$SIZ4 

0$SIZ5 

0$SIZ6 

0$SIZ7 

0$RVB 

0$DVB 

0$IBS 

0$DBS 

0$NSG 

0$TKS 



1 word 
8 words 
word 
word 
word 
word 
word 
word 
word 
word 
8 bytes 
1 byte 
byte 
byte 
byte 
byte 
byte 
byte 
byte 
words 
words 
byte 
byte 
byte 
byte 



1 
1 
1 
1 
1 
1 
1 
2 
2 
1 
1 
1 
1 



Key name buffer address 
Key segment positions 
Key segment position 



Key segment 1 
Key segment 2 
Key segment 3 
Key segment 4 
Key segment 5 
Key segment 6 
Key segment 7 



position 
position 
position 
position 
position 
position 
position 



066 0$MRL 1 word 



Key segment sizes (bytes) 

Key segment size (bytes) 

Key segment 1 size (bytes) 

Key segment 2 size (bytes) 

Key segment 3 size (bytes) 

Key segment 4 size (bytes) 

Key segment 5 size (bytes) 

Key segment 6 size (bytes) 

Key segment 7 size (bytes) 

Root index bucket virtual block number 

First data bucket virtual block number 

Index area bucket size (blocks) 

Data area bucket size (blocks) 

Key segment count 

Total key size (sum of key segment sizes) 

(bytes) 

Minimum length of record containing key 

(bytes) 
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6.4.1 BLN Field in KEY Block (XB$KYL Code) 

DSE Contains the length of the KEY block. 

INIT None 

SIZE 1 byte 

ACCESS $FETCH dst,BLN,reg ;BLN field to 1-byte dst 

$COMPARE src,BLN,reg ; 1-byte src with BLN field 
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6.4.2 COD Field in KEY Block (XB$KEY Code) 

USE Contains the identifier for the KEY block. 

INIT None 

SIZE 1 byte 

ACCESS $FETCH dst,COD,reg ;COD field to 1-byte dst 

$COMPARE src,COD,reg ;l-byte src with COD field 
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6.4.3 DAN Field in KEY Block 



USE 

INIT 
SIZE 
ACCESS 



Contains the area number of the data area for the index 
described by the KEY block. 

X$DAN number 

1 byte 



$FETCH dst,DAN,reg 
$STORE src,DAN,reg 
$COMPARE src,DAN,reg 



;DAN field to 1-byte dst 
;l-byte src to DAN field 
; 1-byte src with DAN field 



INPUT 


CREATE 


Data area number 


OUTPUT 


DISPLAY 


Data area number 




OPEN 


Data area number 
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6.4.4 DBS Field in KEY Block 



USE Contains the bucket size for the data area for the index 
described by the KEY block. 

INIT None 

SIZE 1 byte 

ACCESS $FETCH dst,DBS,reg ;DBS field to 1-byte dst 

$COMPARE src,DBS,reg ;l-byte src with DBS field 

OUTPUT DISPLAY Data area bucket size (blocks) 
OPEN Data area bucket size (blocks) 
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6.4.5 DFL Field in KEY Block 



USE 

INIT 
SIZE 
ACCESS 

INPUT 
OUTPUT 



Contains the bucket fill number for the data area for the 
index described by the KEY block. 

X$DFL number 

1 word 

$FETCH dst,DFL,reg ;DFL field to 1-word dst 
$STORE src,DFL,reg ;l-word src to DFL field 
$COMPARE src,DFL,reg ;l-word src with DFL field 

CREATE Data bucket fill factor 

DISPLAY Data bucket fill factor 
OPEN Data bucket fill factor 
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6.4.6 DTP Field in KEY Block 



USE 

INIT 
SIZE 
ACCESS 

CODES 



INPUT 
OUTPUT 



Contains the key data type code for the index described by 
the KEY block. 

X$DTP code 

1 byte 



$FETCH dst,DTP,reg 
$STORE src,DTP,reg 
$COMPARE src p DTP,reg 



;DTP field to 1-byte dst 
;l-byte src to DTP field 
;l-byte src with DTP field 



XB$BN2 16-bit unsigned integer 

XB$BN4 32-bit unsigned integer 

XB$IN2 15-bit signed integer 

XB$IN4 31-bit signed integer 

XB$PAC Packed decimal number 

XB$STG String 

CREATE Key data type code 

DISPLAY Key data type code 
OPEN Key data type code 
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6.4.7 DVB Field in KEY Block 



USE 



Contains the virtual block number of the first bucket 
the data area for the index described by the KEY block, 



in 



INIT 


None 


SIZE 


2 words 


ACCESS 


$FETCH dst,DVB,reg 


OUTPUT 


DISPLAY First 




OPEN First 



;DVB field to 2-word dst 



First data bucket virtual block number 
First data bucket virtual block number 
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6.4.8 FLG Field in KEY Block (XB$CHG Mask) 



USE 

INIT 
SIZE 
ACCESS 



INPUT 
OUTPUT 



Specifies that a record key (for an alternate 
allowed to change when the record is updated. 

X$FLG mask 



index) is 



1 byte 

$SET mask, FLG, reg 
$OFF mask, FLG, reg 
$TESTBITS mask, FLG, reg 
$FETCH dst,FLG,reg 
$STORE src,FLG,reg 
$COMPARE src,FLG,reg 



;Mask bits on in FLG field 
;Mask bits off in FLG field 
;Test mask bits in FLG field 
;FLG field to 1-byte dst 
;l-byte src to FLG field 
; 1-byte src with FLG field 



CREATE Record key changes allowed on update 

DISPLAY Record key changes allowed on update 
OPEN Record key changes allowed on update 
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6.4.9 FLG Field in KEY Block (XB$DUP Mask) 



USE 

INIT 
SIZE 
ACCESS 



INPUT 
OUTPUT 



Indicates that duplicate record keys are allowed for the 
index described by the KEY block; duplicate record keys 
are not allowed in the primary index. 

X$FLG mask 

1 byte 

$SET mask, FLG, reg ;Mask bits on in FLG field 

$OFF mask, FLG, reg ;Mask bits off in FLG field 

$TESTBITS mask, FLG, reg ;Test mask bits in FLG field 

§FETCH dst,FLG,reg ;FLG field to 1-byte dst 

$STORE src,FLG,reg ; 1-byte src to FLG field 

$COMPARE src, FLG, reg ;l-byte src with FLG field 

CREATE Duplicate record keys allowed 

DISPLAY Duplicate record keys allowed 
OPEN Duplicate record keys allowed 
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6.4.10 FLG Field in KEY Block (XB$NUL Mask) 



USE Indicates that records containing only null characters are 

not contained in the index described by the KEY block. 

(The null character is specified in the NUL field of the 
KEY block.) 

INIT X$FLG mask 

SIZE 1 byte 

ACCESS $SET mask, FLG, reg ;Mask bits on in FLG field 

$OFF mask, FLG, reg ;Mask bits off in FLG field 

$TESTBITS mask, FLG, reg ;Test mask bits in FLG field 

$FETCH dst,FLG,reg ;FLG field to 1-byte dst 

$STORE src,FLG,reg ;l-byte src to FLG field 

$COMPARE src, FLG, reg ;l-byte src with FLG field 

INPUT CREATE Null record keys not indexed 

OUTPUT DISPLAY Null record keys not indexed 
OPEN Null record keys not indexed 
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6.4.11 IAN Field in KEY Block 



USE 

INIT 
SIZE 
ACCESS 

INPUT 
OUTPUT 



Contains the area number of the area containing the higher 
index levels (all except the lowest level) for the index 
described by the KEY block. 

X$IAN number 



1 byte 

$FETCH dst,IAN,reg 
$STORE src,IAN,reg 
$COMPARE src,IAN,reg 



;IAN field to 1-byte dst 
;l-byte src to IAN field 
;l-byte src with IAN field 



CREATE Higher level index area number 

DISPLAY Higher level index area number 
OPEN Higher level index area number 
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6.4.12 IBS Field in KEY Block 



USE 



Contains the bucket size of the area containing the index 
described by the KEY block. 



INIT None 
SIZE 1 byte 

ACCESS $FETCH dst,IBS,reg ;IBS field to 1-byte dst 

$COMPARE src,IBS,reg ;l-byte src with IBS field 

OUTPUT DISPLAY Index area bucket size (blocks) 
OPEN Index area bucket size (blocks) 
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6.4.13 IFL Field in KEY Block 



USE 

INIT 
SIZE 
ACCESS 

INPUT 
OUTPUT 



Contains the bucket fill number for the area containing 
the index described by the KEY block. 

X$IFL number 



1 word 

$FETCH dst,IFL,reg 
$STORE src,IFL,reg 
$COMPARE src,IFL,reg 



;IFL field to 1-word dst 
; 1-word src to IFL field 
;l-word src with IFL field 



CREATE Index bucket fill factor 

DISPLAY Index bucket fill factor 
OPEN Index bucket fill factor 
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6.4.14 KNM Field in KEY Block 



USE 

INIT 
SIZE 
ACCESS 

INPUT 



Contains the address of the 32-byte key name buffer for 
the index described by the KEY block. 

X$KNM address 

1 word 



$FETCH dst,KNM,reg 
$STORE src,KNM,reg 
$COMPARE src,KNM,reg 



;KNM field to 1-word dst 
; 1-word src to KNM field 
; 1-word src with KNM field 



CREATE Key name buffer address 
DISPLAY Key name buffer address 
OPEN Key name buffer address 



6-82 



CONTROL BLOCK FIELDS 
KEY BLOCK SUMMARY 



6.4.15 LAN Field in KEY Block 



USE 

INIT 
SIZE 
ACCESS 

INPUT 
OUTPUT 



Contains the area number of the area containing the lowest 
l^vel of the index described by the KEY block. 

X$LAN number 



1 byte 

$FETCH dst,LAN,reg 
$STORE src,LAN,reg 
$COMPARE src,LAN,reg 



;LAN field to 1-byte dst 
;l-byte src to LAN field 
; 1-byte src with LAN field 



CREATE Lowest index level area number 

DISPLAY Lowest index level area number 
OPEN Lowest index level area number 
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6.4.16 LVL Field in KEY Block 



USE Contains the number of levels (not including the data 
level) for the index described by the KEY block. 

INIT None 

SIZE 1 byte 

ACCESS $FETCH dst,LVL,reg ;LVL field to 1-byte dst 

$COMPARE src,LVL,reg ;l-byte src with LVL field 

OUTPUT DISPLAY Number of index levels (not including data 

level) 
OPEN Number of index levels (not including data 
level) 
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6.4.17 MRL Field in KEY Block 



USE Contains the length of the smallest record that is long 
enough to completely contain a record key for the index 
described by the KEY block. 

INIT None 

SIZE 1 word 

ACCESS $FETCH dst,MRL,reg ;MRL field to 1-word dst 

$COMPARE src,MRL,reg ; 1-word src with MRL field 

OUTPUT DISPLAY Minimum length of record containing key 

(bytes) 
OPEN Minimum length of record containing key 
(bytes) 
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6.4.18 NSG Field in KEY Block 



USE Contains the number of key segments in the key for the 
index described by the KEY block. 

INIT None 

SIZE 1 byte 

ACCESS $FETCH dst,NSG,reg ;NSG field to 1-byte dst 

$COMPARE src,NSG,reg ;l-byte src with NSG field 

OUTPUT DISPLAY Key segment count 
OPEN Key segment count 
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6.4.19 NUL Field in KEY Block 



USE 



Contains the null character for the (alternate) index 
described by the KEY block. For a string key (XB$STG in 
the DTP field of the KEY block) , the NUL field contains an 
ASCII character; for any other key data type, the NUL 
field is unused (nonstring keys use as the null value 
when the XB$NUL mask is set) . 



INIT X$NUL number 

SIZE 1 byte 

ACCESS $FETCH dst,NUL,reg 
$STORE src,NUL,reg 
$COMPARE src,NUL,reg 



;NUL field to 1-byte dst 
;l-byte src to NUL field 
; 1-byte src with NUL field 



INPUT CREATE Null key character 

OUTPUT DISPLAY Null key character 
OPEN Null key character 
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6.4.20 NXT Field in KEY Block 



DSE Contains the address of the next XAB (ALL, DAT, KEY, PRO, 
or SUM block) in a chain of XABs. 

INIT X$NXT address 

SIZE 1 word 

ACCESS $FETCH dst,NXT,reg ;NXT field to 1-word dst 

$STORE src,NXT,reg ;l-word src to NXT field 

$COMPARE src,NXT,reg ;l-word src with NXT field 

INPUT CLOSE Next XAB address 

CREATE Next XAB address 

DISPLAY Next XAB address 

ENTER Next XAB address 

ERASE Next XAB address 

EXTEND Next XAB address 

OPEN Next XAB address 

PARSE Next XAB address 

REMOVE Next XAB address 

RENAME Next XAB address 

SEARCH Next XAB address 
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USE 

INIT 
SIZE 
ACCESS 



INPUT 
OUTPUT 



Contains the positions of segments for the record keys in 
the index described by the KEY block. (The first key 
position is position 0.) 

X$POS <number [, number] .. •> 

8 words 



$FETCH dst,POS,reg 
$STORE src,POS,reg 
$FETCH dst,POSn,reg 
$ST0RE src,POSn,reg 
$COMPARE src,POSn,reg 



POS field to 8-word dst 
8-word src to POS field 
POS word n to 1-word dst 
1-word src to POS word n 
1-word src with POS word 



CREATE Key segment positions 

DISPLAY Key segment positions 
OPEN Key segment positions 
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6.4.22 REF Field in KEY Block 



USE 

INIT 
SIZE 
ACCESS 

INPUT 



Contains the reference number for the index 
the KEY block. 

X$REF number 



described by 



1 byte 

$FETCH dst,REF,reg 
$STORE src,REF,reg 
$COMPARE src,REF,reg 



;REF field to 1-byte dst 
;l-byte src to REF field 
;l-byte src with REF field 



CLOSE Index reference number 

CREATE Index reference number 

DISPLAY Index reference number 

EXTEND Index reference number 

OPEN Index reference number 
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6.4.23 RVB Field in KEY Block 



USE 

INIT 
SIZE 
ACCESS 
OUTPUT 



Contains the virtual block number of the first block of 
the root bucket of the index described by the KEY block. 



None 

2 words 

$FETCH dst,RVB,reg 



;RVB field to 2-word dst 



DISPLAY Root index bucket virtual block number 
OPEN Root index bucket virtual block number 
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6.4.24 SIZ Field in KEY Block 



USE Contains the sizes of segments for the record keys in the 
index described by the KEY block. 

INIT X$SIZ <number [, number] .. .> 

SIZE 8 bytes 

ACCESS $FETCH dst,SIZ,reg ;SIZ field to 8-byte dst 

$STORE src,SIZ,reg ;8-byte src to SIZ field 

$FETCH dst,SIZn,reg ;SIZ byte n to 1-byte dst 

$STORE src,SIZn f reg ;l-byte src to SIZ byte n 

$COMPARE src,SIZn,reg ; 1-byte src with SIZ byte n 

INPUT CREATE Key segment sizes (bytes) 

OUTPUT DISPLAY Key segment sizes (bytes) 
OPEN Key segment sizes (bytes) 
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6.4.25 TKS Field in KEY Block 



USE 



Contains the total key size (sum of the segment sizes) 
a record key for the index described by the KEY block. 



of 



INIT 


None 






SIZE 


1 byte 






ACCESS 


$FETCH dst,TKS,reg 
$COMPARE src,TKS,reg 


;TKS field to 1-byte dst 
;l-byte src with TKS field 




OUTPUT 


DISPLAY Total key 
(bytes) 

OPEN Total key 
(bytes) 


size (sum of key segment 
size (sum of key segment 


sizes) 
sizes) 
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6.5 NAM BLOCK SUMMARY 

This section summarizes the NAM block and its fields. Table 6-5 
summarizes the entire block, giving the offset, offset symbol, size, 
and a brief description for each field; for a field that has mask or 
code symbols, the table also gives the value, symbol, and a brief 
description for each mask or code. 



Table 6-5: NAM Block Summary 



Offset Field 
Offset Symbol Size 



Description 



000 0$RLF 1 word Reserved 

002 0$RSA 1 word Resultant string buffer address 

004 0$RSS 1 byte Resultant string buffer size (bytes) 

005 0$RSL 1 byte Resultant string length (bytes) 

006 0$DVI 2 words Device identifier 

012 0$WDI 1 word Wildcard directory context 

014 0$FID 3 words File identifier 

022 0$DID 3 words Directory identifier 

030 0$FNB 1 word File specification mask 

000001 NB$VER File version in file 

string or default string 

000002 NB$TYP File type in file string 

or default string 
000004 NB$NAM File name in file string 

or default string 
000010 NB$WVE Wildcard file version in 

file string or default 

string 
000020 NB$WTY Wildcard file type in 

file string or default 

string 
000040 NB$WNA Wildcard file name in 

file string or default 

string 
000100 NB$DIR Directory in file string 

or default string 
000200 NB$DEV Device in file string or 

default string 
000400 NB$NOD Node in file string or 

default string 
001000 NB$WDI Wildcard directory in 

file string or default 

string 
002000 NB$QUO Quoted string in file 

string or default string 
004000 NB$WCH Wildcard context 

established 



03 2 .;', 0$^SA 1 word 

034 0$ESS 1 byte 

035 0$ESL . 1 byte 

036 0$WCC 1 word 



Expanded string buffer address 

Expanded string buffer size (bytes) 

Expanded string length (bytes) 
Wildcard context 



The first word of the NAM block is currently reserved, as noted above, 
and must contain the value 0. If the NAM block is extended in the 
future, the first byte will contain an identifier and the second byte 
will contain the (new) block length. 
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6.5.1 DID Field in NAM Block 



USE 

INIT 

SIZE 

ACCESS 

INPUT 



OUTPUT 



Contains the directory identifier for the target file. 

None 

3 words 

$FETCH dst,DID,reg 



CREATE 

ENTER 

ERASE 

OPEN 

REMOVE 

RENAME 

SEARCH 

CREATE 

ENTER 

ERASE 

OPEN 

PARSE 

REMOVE 

RENAME 

SEARCH 



;DID field to 3-word dst 

Directory identifier 
Directory identifier 
Directory identifier 
Directory identifier 
Directory identifier 
Directory identifier 
Directory identifier 

Directory identifier 

Directory identifier 

Directory identifier 

Directory identifier 

Directory identifier (cleared) 

Directory identifier 

Directory identifier 

Directory identifier 
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6.5.2 DVI Field in NAM Block 



USE 


Contains 


the device identifie 


INIT 


None 






SIZE 


2 words 






ACCESS 


$FETCH dst,DVI,reg 


;DVI f 


INPUT 


CREATE 


Device 


identifier 




ENTER 


Device 


identifier 




ERASE 


Device 


identifier 




OPEN 


Device 


identifier 




REMOVE 


Device 


identifier 




RENAME 


Device 


identifier 




SEARCH 


Device 


identifier 


OUTPUT 


CREATE 


Device 


identifier 




ENTER 


Device 


identifier 




ERASE 


Device 


identifier 




OPEN 


Device 


identifier 




PARSE 


Device 


identifier 




REMOVE 


Device 


identifier 




RENAME 


Device 


identifier 



;DVI field to 2-word dst 
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USE 
INIT 
SIZE 
ACCESS 

INPUT 



Contains the address of the expanded string buffer 
N$ESA address 
1 word 



$FETCH dst,ESA,reg 
$STORE src,ESA,reg 
$COMPARE src,ESA,reg 



ESA field to 1-word dst 
1-word src to ESA field 
1-word src with ESA field 



CREATE 


Expanded 


string 


buffer 


address 


ENTER 


Expanded 


string 


buffer 


address 


ERASE 


Expanded 


string 


buffer 


address 


OPEN 


Expanded 


string 


buffer 


address 


PARSE 


Expanded 


string 


buffer 


address 


REMOVE 


Expanded 


string 


buffer 


address 


RENAME 


Expanded 


string 


buffer 


address 


SEARCH 


Expanded 


string 


buffer 


address 
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6.5.4 ESL Field in NAM Block 



USE 
IN IT 
SIZE 
ACCESS 

INPDT 
OUTPUT 



Contains the length of the expanded string, 
None 



1 byte 

$FETCH dst,ESL,reg 
$COMPARE src,ESL,reg 

SEARCH 



CREATE 

ENTER 

ERASE 

OPEN 

PARSE 

REMOVE 

RENAME 



;ESL field to 1-byte dst 
;l-byte src with ESL field 



Expanded 


string 


length 


(bytes) 


Expanded 


string 


length 


(bytes) 


Expanded 


string 


length 


(bytes) 


Expanded 


string 


length 


(bytes) 


Expanded 


string 


length 


(bytes) 


Expanded 


string 


length 


(bytes) 


Expanded 


string 


length 


(bytes) 


Expanded 


string 


length 


(bytes) 
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USE 
INIT 
SIZE 
ACCESS 

INPUT 



Contains the size of the expanded string buffer, 
N$ESS number 



1 byte 

$FETCH dst,ESS,reg 
$STORE src,ESS,reg 
$COMPARE src,ESS,reg 



;ESS field to 1-byte dst 
;l-byte src to ESS field 
;l-byte src with ESS field 



CREATE Expanded string 

ENTER Expanded string 

ERASE Expanded string 

OPEN Expanded string 

PARSE Expanded string 

REMOVE Expanded string 

RENAME Expanded string 



buffer size 
buffer size 
buffer size 
buffer size 
buffer size 
buffer size 
buffer size 



(bytes) 
(bytes) 
(bytes) 
(bytes) 
(bytes) 
(bytes) 
(bytes) 
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6.5.6 FID Field in NAM Block 



USE 


Contain 


INIT 


None 


SIZE 


3 words 


ACCESS 


$FETCH ■ 


INPUT 


ENTER 




ERASE 




OPEN 




REMOVE 


OUTPUT 


CREATE 




ERASE 




OPEN 




REMOVE 




RENAME 




SEARCH 



Contains the file identifier for the target file. 



riD,reg ;FID field to 3-word dst 

File identifier 
File identifier 
File identifier 
File identifier 

File identifier 
File identifier 
File identifier 
File identifier 
File identifier 
File identifier (only if FB$FID mask is set) 
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6.5.7 FNB Field in NAM Block 



USE 

INIT 
SIZE 
ACCESS 

MASKS 



OUTPUT 



Indicates which parts of the merged string were taken from 

the file string or the default string. (The masks in this 

section do not include the NB$WCH mask, which has its own 
description in the next section.) 

None 

1 word 

$TESTBITS mask, FNB, reg ;Test mask bits in FNB field 
$FETCH dst,FNB,reg ;FNB field to 1-word dst 
$COMPARE src,FNB,reg ;l-word src with FNB field 



NB$DEV 
NB$DIR 
NB$NAM 
NB$NOD 
NB$QUO 
NB$TYP 
NB$VER 
NB$WDI 

NB$WNA 

NB$WTY 

NB$WVE 



CREATE 

ENTER 

ERASE 

OPEN 

PARSE 

REMOVE 

RENAME 



Device in 

Directory 

File name 

Node in f 

Quoted st 

File type 

File vers 

Wildcard 

string 

Wildcard 

string 

Wildcard 

string 

Wildcard 

string 



file string or default string 
in file string or default string 
in file string or default string 
ile string or default string 
ring in file string or default string 

in file string or default string 
ion in file string or default string 
directory in file string or default 

file name in file string or default 

file type in file string or default 

file version in file string or default 



File specification mask 
File specification mask 
File specification mask 
File specification mask 
File specification mask 
File specification mask 
File specification mask 
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6.5.8 FNB Field in NAM Block (NB$WCH Mask) 



USE 

INIT 
SIZE 
ACCESS 



INPUT 


ERASE 




OPEN 




REMOVE 




RENAME 




SEARCH 


OUTPUT 


CREATE 




ENTER 




OPEN 




PARSE 




SEARCH 



Indicates that a valid wildcard context exists. (Masks 
for the FNB field other than the NB$WCH mask are described 
in the previous section.) 

None 

1 word 

$TESTBITS mask, FNB, reg ;Test mask bits in FNB field 
$FETCH dst,FNB,reg ;FNB field to 1-word dst 
$COMPARE src,FNB,reg ;l-word src with FNB field 

Wildcard context established 
Wildcard context established 
Wildcard context established 
Wildcard context established 
Wildcard context established 

Wildcard context established 
Wildcard context established 
Wildcard context established 
Wildcard context established 
Wildcard context established 
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6.5.9 RSA Field in NAM Block 



USE 
INIT 
SIZE 
ACCESS 

INPUT 



Contains the address of the resultant string buffer. 
N$RSA address 
1 word 



$FETCH dst,RSA,reg 
$STORE src,RSA,reg 
$COMPARE src,RSA,reg 



;RSA field to 1-word dst 
; 1-word src to RSA field 
; 1-word src with RSA field 



SEARCH 



Resultant string buffer address 
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6.5.10 RSL Field in NAM Block 



USE 
INIT 
SIZE 
ACCESS 

INPUT 
OUTPUT 



Contains the length of the resultant string. 

None 

1 byte 

$FETCH dst,RSL,reg ;RSL field to 1-byte dst 
$COMPARE src,RSL,reg ;l-byte src with RSL field 

SEARCH Resultant string length (bytes) 

SEARCH Resultant string length (bytes) 
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6.5.11 RSS Field in NAM Block 



DSE 
INIT 
SIZE 
ACCESS 

INPUT 



Contains the size of the resultant string buffer 
N$RSS number 
1 byte 



$FETCH dst,RSS,reg 
$STORE src,RSS,reg 
$COMPARE src,RSS,reg 



;RSS field to 1-byte dst 
;l-byte src to RSS field 
;l-byte src with RSS field 



SEARCH 



Resultant string buffer size (bytes) 
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6.5.12 WCC Field in NAM Block 



USE 
INIT 
SIZE 
ACCESS 

INPUT 
OUTPUT 



Contains wildcard context information. 

None 

1 word 

$FETCH dst f WCC,reg ;WCC field to 1-word dst 

$COMPARE src,WCC,reg ; 1-word src with WCC field 

SEARCH Wildcard context 

PARSE Wildcard context 

SEARCH Wildcard context 
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6.5.13 WDI Field in NAM Block 



USE 
INIT 
SIZE 
ACCESS 

INPUT 
OUTPUT 



Contains wildcard directory context information. 

None 

1 word 

$FETCH dst,WDI,reg ;WDI field to 1-word dst 
$COMPARE src,WDI,reg ;l-word src with WDI field 

SEARCH Wildcard directory context 

PARSE Wildcard directory context 
SEARCH Wildcard directory context 
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6.6 PRO BLOCK SUMMARY 



This section summarizes the PRO block and its fields. Table 6-6 
summarizes the entire block, giving the offset, offset symbol, size, 
and a brief description for each field; for a field that has mask or 
code symbols, the table also gives the value, symbol, and a brief 
description for each mask or code. 



Table 6-6 : PRO Block Summary 



Offset Field 
Offset Symbol Size 



Description 



000 0$COD 1 byte 



001 0$BLN 1 byte 



002 


0$NXT 


1 


word 


004 


0$PRG 


1 


word 


006 


0$PRJ 


1 


word 


010 


0$PRO 


1 


word 



PRO block identifier 

000003 XB$PRO PRO block identifier code 

PRO block length (bytes) 

000012 XB$PRL PRO block length (bytes) 

Next XAB address 

Programmer or member portion of file 

owner code 

Project or group portion of file owner 

code 

File protection code 
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6.6.1 BLN Field in PRO Block (XB$PRL Code) 

USE Contains the length Of the PRO block. 

INIT None 

SIZE 1 byte 

ACCESS $FETCH dst,BLN,reg ;BLN field to 1-byte dst 

$COMPARE src,BLN,reg ; 1-byte src with BLN field 
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6.6.2 COD Field in PRO Block (XB$PRO Code) 

USE Contains the identifier for the PRO block. 

INIT None 

SIZE 1 byte 

ACCESS $FETCH dst,COD,reg ;COD field to 1-byte dst 

$COMPARE src,COD,reg ; 1-byte src with COD field 
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6.6.3 NXT Field in PRO Block 



USE 



INIT 



Contains the address of the next XAB (ALL, DAT, KEY, 
or SUM block) in a chain of XABs. 

X$NXT address 



PRO, 



SIZE 



ACCESS 



INPUT 



1 word 

$FETCH dst,NXT,reg 
$STORE src,NXT,reg 
$COMPARE src,NXT,reg 



;NXT field to 1-word dst 
; 1-word src to NXT field 
;l-word src with NXT field 



CLOSE Next XAB address 

CREATE Next XAB address 

DISPLAY Next XAB address 

ENTER Next XAB address 

ERASE Next XAB address 

EXTEND Next XAB address 

OPEN Next XAB address 

PARSE Next XAB address 

REMOVE Next XAB address 

RENAME Next XAB address 

SEARCH Next XAB address 
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6.6.4 PRG Field in PRO Block 



USE 



Contains the member or programmer portion of the file 
owner code. 



INIT X$PRG number 
SIZE 1 word 

ACCESS $FETCH dst,PRG,reg ;PRG field to 1-word dst 
$STORE src,PRG,reg ; 1-word src to PRG field 
$COMPARE src,PRG,reg ;l-word src with PRG field 

INPUT CLOSE Programmer or member portion of file owner 

code 

OUTPUT DISPLAY Programmer or member portion of file owner 

code 
OPEN Programmer or member portion of file owner 
code 
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6.6.5 PRJ Field in PRO Block 



USE 

INIT 
SIZE 
ACCESS 

INPUT 
OUTPUT 



Contains the group or project portion of the file owner 
code. 

X$PRJ number 

1 word 

$FETCH dst,PRJ,reg ;PRJ field to 1-word dst 
$STORE src,PRJ,reg ;l-word src to PRJ field 
$COMPARE src,PRJ,reg ;l-word src with PRJ field 



CLOSE 



Project or group portion of file owner code 



DISPLAY Project or group portion of file owner code 
OPEN Project or group portion of file owner code 
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6.6.6 PRO Field in PRO Block 

OSE Contains the protection code for the file. 

INIT X$PRO number 

SIZE 1 word 

ACCESS $FETCH dst,PRO,reg ;PRO field to 1-word dst 
$STORE src,PRO,reg ;l-word src to PRO field 
$COMPARE src,PRO,reg ;l-word src with PRO field 

INPUT CLOSE File protection code 
CREATE File protection code 

OUTPUT DISPLAY File protection code 
OPEN File protection code 
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6.7 RAB SUMMARY 

This section summarizes the RAB and its fields. Table 6-7 summarizes 
the entire block, giving the offset, offset symbol, size, and a brief 
description for each field; for 
symbols, the table also gives 
description for each mask or code, 



a field that has mask 
the value, symbol, and 



or code 
a brief 



Table 6-7: RAB Summary 



Offset Field 
Offset Symbol Size 



Description 



000 0$BID 



001 



021 
022 



024 
026 
030 
032 
034 
036 
037 
040 
041 
042 
044 
046 



0$KSZ 
0$ROP 



1 byte RAB identifier code 

000001 RB$BID RAB identifier 



0$BLN 1 byte RAB length (bytes) 



002 


0$CTX 


1 


word 


004 


0$ISI 


1 


word 


006 


0$STS 


1 


word 


010 


0$STV 


1 


word 


012 


0$RFA 


3 


words 


020 


0$RAC 


1 


byte 



O$0SZ 

0$UBF 

0$RSZ 

0$RBF 

0$KBF 

0$KRF 

0$MBF 

0$MBC 

0$RT1A 

0$RHB 

0$FAB 

0$BKT 



1 byte 
1 word 



word 
word 
word 
word 
word 
byte 
byte 
byte 
byte 
word 
word 
words 



000120 RB$BLN Synchronous RAB length 

(bytes) 
000240 RB$BLL Asynchronous RAB length 

(bytes) 

User context 

Internal stream identifier 
Completion status code 
Completion status value 
Record file address 
Record access code 

000000 RB$SEQ Sequential access 

000001 RB$KEY Key access 

000002 RB$RFA RFA access 

Key size (bytes) 

Record processing option mask 

000001 RB$EOF Position to end-of-file 

000002 RB$MAS Mass insert 

000020 RB$L0A Honor bucket fill numbers 
000100 RB$L0C Locate mode 
000200 RB$ASY Asynchronous operation 
002000 RB$KGE Greater-than-or-equal key 

criterion 
004000 RB$KGT Greater-than key 

criterion 
010000 RB$FDL Fast deletion 
020000 RB$UIF Update if record exists 

User buffer size (bytes) 

User buffer address 

Record size (bytes) 

Record buffer address 

Key buffer address 

Key of reference 

Multibuffer count 

Multiblock count 

Reserved 

VFC control buffer address 

FAB address 

Virtual block number. (VBN) or relative 

record number (RRN) 
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6.7.1 BID Field in RAB (RB$BID Code) 

USE Contains the identifier for the RAB. 

INIT None 

SIZE 1 byte 

ACCESS $FETCH dst,BID,reg ;BID field to 1-byte dst 

$COMPARE src,BID,reg ;l-byte src with BID field 
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6.7.2 BKT Field in RAB 



USE 

INIT 
SIZE 
ACCESS 



Contains a virtual block number or relative record number 
for a target record. 

R$BKT number 



2 words 

$FETCH dst,BKT,reg 
$STORE src,BKT,reg 
$FETCH dst,BKTn,reg 
$STORE src,BKTn,reg 
$COMPARE src,BKTn,reg 



;BKT field to 2-word dst 
; 2-word src to BKT field 
;BKT word n to 1-word dst 
; 1-word src to BKT word n 
; 1-word src with BKT word 



INPUT 


READ 




SPACE 




WRITE 


OUTPUT 


FIND 




GET 




PUT 



Virtual block number (VBN) 

Virtual block number (VBN) increment 

Virtual block number (VBN) 

Relative record number (RRN) 
Relative record number (RRN) 
Relative record number (RRN) 
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6.7.3 BLN Field in RAB 



USE Contains the length of the RAB. 

INIT None 

SIZE 1 byte 

ACCESS $FETCH dst,BLN,reg ;BLN field to 1-byte dst 

$COMPARE src,BLN,reg ;l-byte src with BLN field 

CODES RB$BLL Asynchronous RAB length (bytes) 
RB$BLN Synchronous RAB length (bytes) 
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6.7.4 CTX Field in RAB 



USE 



Contains any information you may want 
the stream at run time. 



to associate with 



INIT R$CTX number 

SIZE 1 word 

ACCESS $FETCH dst,CTX,reg 
$STORE src,CTX,reg 
$COMPARE src,CTX,reg 



;CTX field to 1-word dst 
; 1-word src to CTX field 
;l-word src with CTX field 
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6.7.5 FAB Field in RAB 



USE Contains the address of the FAB for the target file. 

INIT R$FAB address 

SIZE 1 word 

ACCESS $FETCH dst,FAB,reg ;FAB field to 1-word dst 
$STORE src,FAB,reg ;l-word src to FAB field 
$COMPARE src,FAB,reg ;l-word src with FAB field 

INPUT CONNECT FAB address 



6-120 



CONTROL BLOCK FIELDS 
RAB SUMMARY 



6.7.6 ISI Field in RAB 



USE 



Contains the internal stream 
file. 



identifier for the target 



INIT 
SIZE 
ACCESS 

INPUT 



None 



1 word 



$FETCH dst,ISI,reg 
$COMPARE src,ISI,reg 



DELETE 

DISCONNECT 

FIND 

FLUSH 

FREE 

GET 

NXTVOL 

PUT 

READ 

REWIND 

SPACE 

TRUNCATE 

UPDATE 

WAIT 

WRITE 



;ISI field to 1-word dst 
; 1-word src with ISI field 



Internal 
Internal 
Internal 
Internal 
Internal 
Internal 
Internal 
Internal 
Internal 
Internal 
Internal 
Internal 
Internal 
Internal 
Internal 



stream 
stream 
stream 
stream 
stream 
stream 
stream 
stream 
stream 
stream 
stream 
stream 
stream 
stream 
stream 



identifier 
identifier 
identifier 
identifier 
identifier 
identifier 
identifier 
identifier 
identifier 
identifier 
identifier 
identifier 
identifier 
identifier 
identifier 



OUTPUT 



CONNECT Internal stream identifier 
DISCONNECT Internal stream identifier 
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6.7.7 KBF Field in RAB 



USE Contains the address of the key buffer for the target 
record . 

INIT R$KBP address 

SIZE 1 word 

ACCESS $FETCH dst,KBF,reg ;KBF field to 1-word dst 

$STORE src,KBF,reg ;l-word src to KBF field 

$COMPARE src,KBF,reg ;l-word src with KBF field 

INPUT FIND Key buffer address 

GET Key buffer address 

PUT Key buffer address 
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6.7.8 KRF Field in RAB 



USE 



INIT 



Contains the index reference number of the index 
operation. 

R$KRF number 



for the 



SIZE 



ACCESS 



INPUT 



1 byte 

$FETCH dst,KRF,reg 
$STORE src,KRF,reg 
$COMPARE src,KRF,reg 



;KRF field to 1-byte dst 
;l-byte src to KRF field 
; 1-byte src with KRF field 



CONNECT Key of reference 

FIND Key of reference 

GET Key of reference 

REWIND Key of reference 
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6.7.9 KSZ Field in RAB 



DSE Contains the size of the record key for the operation, 

INIT R$KSZ number 

SIZE 1 byte 

ACCESS . $FETCH dst,KSZ,reg ;KSZ field to 1-byte dst 

$STORE src,KSZ,reg ; 1-byte src to KSZ field , 

$COMPARE src,KSZ,reg ; 1-byte src with KSZ field 

INPUT FIND Key size (bytes) 

GET Key size (bytes) 

PUT Key size (bytes) 
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6.7.10 MBC Field in RAB 



USE 
INIT 
SIZE 
ACCESS 



INPUT 



Contains the multiblock count for the stream. 
R$MBC number 
1 byte 



$FETCH dst,MBC,reg 
$STORE src,MBC,reg 
$COMPARE src,MBC,reg 



;MBC field to 1-byte dst 
;l-byte src to MBC field 
;l-byte src with MBC field 



CONNECT 



Multiblock count 
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6.7.11 MBF Field in RAB 

USE Contains the multibuffer count for the stream. 
INIT R$MBF number 
SIZE 1 byte 



ACCESS $FETCH dst,MBF,reg 
$STORE src,MBF,reg 
$COMPARE src,MBF,reg 



MBF field to 1-byte dst 
1-byte src to MBF field 
1-byte src with MBF field 



INPUT CONNECT Multibuffer count 
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6.7.12 RAC Field in RAB 



USE 
INIT 
SIZE 
ACCESS 



CODES 



INPUT 



Contains the access mode code for the operation. 
R$RAC code 



1 byte 

$FETCH dst,RAC,reg 
$STORE src,RAC,reg 
$COMPARE src,RAC,reg 



;RAC field to 1-byte dst 
;l-byte src to RAC field 
; 1-byte src with RAC field 



RB$KEY Key access 

RB$RFA RFA access 

RB$SEQ Sequential access 

FIND Record access code 
GET Record access code 
PUT Record access code 
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6.7.13 RBF Field in RAB 



USE 

INIT 
SIZE 
ACCESS 



Contains the address of the record buffer for 
operation. 

R$RBF address 

1 word 



the 



$FETCH dst,RBF,reg 
$STORE src,RBF,reg 
$COMPARE src,RBF,reg 



RBF field to 1-word dst 
1-word src to RBF field 
1-word src with RBF field 



INPUT 


PUT 




UPDATE 




WRITE 


OUTPUT 


CONNECT 




GET 




PUT 




READ 



Record buffer address 
Record buffer address 
Record buffer address 

Record buffer address 
Record buffer address 
Record buffer address 
Record buffer address 
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6.7.14 RFA Field in RAB 



DSE 


Contain 


INIT 


None 


SIZE 


3 words 


ACCESS 


$FETCH . 


INPUT 


FIND 




GET 


OUTPUT 


CONNECT 




FIND 




GET 




PUT 




READ 




WRITE 



Contains the record file address for the target record, 



*FA,reg ;RFA field to 3-word dst 

Record file address 
Record file address 

End-of-file address 

Record file address 

Record file address 

Record file address 

Virtual block number (2 words) 

Virtual block number (2 words) 
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6.7.15 RHB Field in RAB 



USE Contains the address of the VFC fixed control area buffer 
for the target record. 

INIT R$RHB address 

SIZE 1 word 

ACCESS $FETCH dst,RHB,reg ;RHB field to 1-word dst 
$STORE src,RHB,reg ;l-word src to RHB field 
$COMPARE src,RHB,reg ;l-word src with RHB field 

INPUT GET VFC control buffer address 
PUT VFC control buffer address 
UPDATE VFC control buffer address 
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CONTROL BLOCK FIELDS 
RAB SUMMARY 



USE 
INIT 
SIZE 
ACCESS 



INPUT 



Requests asynchronous operation. 
R$ROP mask 
1 word 



$SET mask, ROP, reg 
$OFF mask, ROP, reg 
$TESTBITS mask, ROP, reg 
$FETCH dst,ROP,reg 
$STORE src,ROP,reg 
$COMPARE src,ROP,reg 



;Mask bits on in ROP field 
;Mask bits off in ROP field 
;Test mask bits in ROP field 
;ROP field to 1-word dst 
; 1-word src to ROP field 
;l-word src with ROP field 



CONNECT 

DELETE 

DISCONNECT 

FIND 

FLUSH 

FREE 

GET 

NXTVOL 

PUT 

READ 

REWIND 

SPACE 

TRUNCATE 

UPDATE 

WRITE 



Asynch 
Asynch 
Asynch 
Asynch 
Asynch 
Asynch 
Asynch 
Asynch 
Asynch 
Asynch 
Asynch 
Asynch 
Asynch 
Asynch 
Asynch 



ronous 
ronous 
ronous 
ronous 
ronous 
ronous 
ronous 
ronous 
ronous 
ronous 
ronous 
ronous 
ronous 
ronous 
ronous 



opera 
opera 
opera 
opera 
opera 
opera 
opera 
opera 
opera 
opera 
opera 
opera 
opera 
opera 
opera 



tion 
tion 
tion 
tion 
tion 
tion 
tion 
tion 
tion 
tion 
tion 
tion 
tion 
tion 
tion 
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6.7.17 ROP Field in RAB (RB$EOF Mask) 



USE 
INIT 
SIZE 
ACCESS 



Requests initial stream context at end-of-f ile. 
R$ROP mask 



1 word 

$SET mask, ROP, reg 
$OFF mask, ROP, reg 



;Mask bits on in ROP field 
;Mask bits off in ROP field 
$TESTBITS mask, ROP, reg ;Test mask bits in ROP field 



$FETCH dst,ROP,reg 
$STORE src,ROP,reg 
$COMPARE src,ROP,reg 



;ROP field to 1-word dst 
; 1-word src to ROP field 
; 1-word src with ROP field 



INPUT 



CONNECT 



Position to end-of-file 
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6.7.18 ROP Field in RAB (RB$FDL Mask) 



USE 
INIT 
SIZE 
ACCESS 



Requests fast deletion. 

R$ROP mask 

1 word 

$SET mask, ROP, reg 
$OFF mask, ROP, reg 



;Mask bits on in ROP field 
;Mask bits off in ROP field 
$TESTBITS mask, ROP, reg ;Test mask bits in ROP field 



$FETCH dst,ROP,reg 
$STORE src,ROP,reg 
$COMPARE src,ROP,reg 



;ROP field to 1-word dst 
; 1-word src to ROP field 
; 1-word src with ROP field 



INPUT 



DELETE 



Fast deletion 
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6.7.19 ROP Field in RAB (RB$KGE Mask) 

USE Requests greater-than-or-equal key match criterion. 

INIT R$ROP mask 

SIZE 1 word 

ACCESS $SET mask, ROP, reg ;Mask bits on in ROP field 

$OFF mask, ROP, reg ;Mask bits off in ROP field 

$TESTBITS mask, ROP, reg ;Test mask bits in ROP field 

$FETCH dst,ROP,reg ;ROP field to 1-word dst 

$STORE src,ROP,reg ;l-word src to ROP field 

$COMPARE src, ROP, reg ;l-word src with ROP field 

INPUT FIND Greater-than-or-equal key criterion 
GET Greater-than-or-equal key criterion 
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6.7.20 ROP Field in RAB (RB$KGT Mask) 



USE 
INIT 
SIZE 
ACCESS 



INPUT 



Requests greater-then key match criterion. 

R$ROP mask 

1 word 

$SET mask, ROP, reg ;Mask bits on in ROP field 

$OFF mask, ROP, reg ;Mask bits off in ROP field 

$TESTBITS mask, ROP, reg ;Test mask bits in ROP field 

$FETCH dst,ROP,reg ;ROP field to 1-word dst 

$STORE src,ROP,reg ; 1-word src to ROP field 

$COMPARE src, ROP, reg ;l-word src with ROP field 



FIND 
GET 



Greater-than key criterion 
Greater-than key criterion 
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6.7.21 ROP Field in RAB (RB$LOA Mask) 



USE 
INIT 
SIZE 
ACCESS 



INPUT 



Requests bucket fill number honoring. 

R$ROP mask 

1 word 

$SET mask, ROP, reg ;Mask bits on in ROP field 

$OFF mask, ROP, reg ;Mask bits off in ROP field 

$TESTBITS mask, ROP, reg ;Test mask bits in ROP field 

$FETCH dst,ROP,reg ;ROP field to 1-word dst 

$STORE src,ROP,reg ;l-word src to ROP field 

$COMPARE src, ROP, reg ;l-word src with ROP field 

PUT Honor bucket fill numbers 
UPDATE Honor bucket fill numbers 
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USE 
INIT 
SIZE 
ACCESS 



Requests locate mode operation. 

R$ROP mask 

1 word 

$SET mask, ROP, reg ;Mask bits on in ROP field 

$OFF mask, ROP, reg ;Mask bits off in ROP field 

$TESTBITS mask, ROP, reg ;Test mask bits in ROP field 

$FETCH dst,ROP,reg ;ROP field to 1-word dst 

$STORE src,ROP,reg ; 1-word src to ROP field 

$COMPARE src, ROP, reg ;l-word src with ROP field 



INPOT 



CONNECT 


Locate 


mode 


GET 


Locate 


mode 


PUT 


Locate 


mode 
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6.7.23 ROP Field in RAB <RB$MAS Mask) 



USE 
INIT 
SIZE 
ACCESS 



Requests mass insertion. 

R$ROP mask 

1 word 

$SET mask, ROP, reg ;Mask bits on in ROP field 

$OFF mask, ROP, reg ;Mask bits off in ROP field 

$TESTBITS mask, ROP, reg ;Test mask bits in ROP field 

$FETCH dst,ROP,reg ;ROP field to 1-word dst 

$STORE src,ROP,reg ; 1-word src to ROP field 

$COMPARE src, ROP, reg ;l-word src with ROP field 



INPUT 



PUT 



Mass insert 
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6.7.24 ROP Field in RAB (RB$UIF Mask) 



USE 
INIT 
SIZE 
ACCESS 



Requests update if target record already exists. 
R$ROP mask 
1 word 



$SET mask, ROP, reg 
$OFF mask, ROP, reg 
$TESTBITS mask, ROP, reg 
$FETCH dst,ROP,reg 
$STORE src,ROP,reg 
$COMPARE src,ROP,reg 



;Mask bits on in ROP field 
;Mask bits off in ROP field 
;Test mask bits in ROP field 
;ROP field to 1-word dst 
; 1-word src to ROP field 
;l-word src with ROP field 



INPUT 



PUT 



Update if record exists 
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6.7.25 RSZ Field in RAB 



USE 
INIT 
SIZE 
ACCESS 



Contains the size of the target record. 
R$RSZ number 



1 word 

$FETCH dst,RSZ,reg 
$STORE src,RSZ,reg 
$COMPARE src,RSZ,reg 



;RSZ field to 1-word dst 
; 1-word src to RSZ field 
;l-word src with RSZ field 



INPUT 


PUT 




UPDATE 




WRITE 


OUTPUT 


GET 




READ 



Record size (bytes) 

Record size (bytes) 

Record size (bytes) 

Record size (bytes) 

Record size (bytes) 
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6.7.26 STS Field in RAB 



USE 
INIT 
SIZE 
ACCESS 

OUTPUT 



Contains the completion status code for the operation, 



None 



1 word 



$FETCH dst,STS,reg 
$COMPARE src,STS,reg 



;STS field to 1-word dst 
;l-word src with STS field 



CONNECT 


Completion 


status 


code 


DELETE 


Completion 


status 


code 


DISCONNECT 


Completion 


status 


code 


FIND 


Completion 


status 


code 


FLUSH 


Completion 


status 


code 


FREE 


Completion 


status 


code 


GET 


Completion 


status 


code 


NXTVOL 


Completion 


status 


code 


PUT 


Completion 


status 


code 


READ 


Completion 


status 


code 


REWIND 


Completion 


status 


code 


SPACE 


Completion 


status 


code 


TRUNCATE 


Completion 


status 


code 


UPDATE 


Completion 


status 


code 


WRITE 


Completion 


status 


code 
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6.7.27 STV Field in RAB 



USE 
INIT 
SIZE 
ACCESS 

OUTPUT 



Contains the completion status value for the operation. 
None 



1 word 

$FETCH dst,STV,reg 
$COMPARE src,STV,reg 



;STV field to 1-word dst 
;l-word src with STV field 



CONNECT 


Completion 


status 


value 


DELETE 


Completion 


status 


value 


DISCONNECT 


Completion 


status 


value 


FIND 


Completion 


status 


value 


FLUSH 


Completion 


status 


value 


FREE 


Completion 


status 


value 


GET 


Completion 


status 


value 


NXTVOL 


Completion 


status 


value 


PUT 


Completion 


status 


value 


READ 


Completion 


status 


value 


REWIND 


Completion 


status 


value 


SPACE 


Completion 


status 


value 


TRUNCATE 


Completion 


status 


value 


UPDATE 


Completion 


status 


value 


WRITE 


Completion 


status 


value 
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USE 
INIT 
SIZE 
ACCESS 

INPUT 



Contains the address of the user buffer for the operation. 
R$UBF address 



1 word 

$FETCH dst,UBF,reg 
$STORE src,UBF,reg 
$COMPARE src,UBF,reg 



;UBF field to 1-word dst 
;l-word src to UBF field 
;l-word src with UBF field 



CONNECT User buffer address 

GET User buffer address 

PUT User buffer address 

READ User buffer address 
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6.7.29 USZ Field in RAB 



DSE 
INIT 
SIZE 
ACCESS 

INPUT 



Contains the size of the user buffer for the operation. 
R$USZ number 
1 word 



$FETCH dst,USZ,reg 
$STORE src,USZ,reg 
$COMPARE src,USZ,reg 



;USZ field to 1-word dst 
; 1-word src to USZ field 
;l-word src with USZ field 



CONNECT 
GET 
PUT 
READ 



User buffer size (bytes) 

User buffer size (bytes) 

User buffer size (bytes) 

User buffer size (bytes) 
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6.8 SUM BLOCK SUMMARY 

This section summarizes the SUM block and its fields. Table 6-8 
summarizes the entire block, giving the offset, offset symbol, size, 
and a brief description for each field; for a field that has mask or 
code symbols, the table also gives the value, symbol, and a brief 
description for each mask or code. 



Table 6-8: SUM Block Summary 



Offset Field 
Offset Symbol Size 



Description 



000 



0$COD 1 byte 



001 0$BLN 1 byte 



SUM block identifier 

000005 XB$SUM SUM block identifier code 

SUM block length (bytes) 

000012 XB$SML SUM block length (bytes) 



002 


0$NXT 


1 word 


Next XAB address 


004 


0$NOK 


1 byte 


Number of indexes 


005 


0$NOA 


1 byte 


Number of areas 


006 


0$NOR 


1 byte 


Reserved 


007 




1 byte 


Reserved 


010 


0$PVN 


1 word 


Prologue version number 
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6.8.1 BLN Field in SOM Block (XB$SML Code) 

USE Contains the length of the SUM block. 

INIT None 

SIZE 1 byte 

ACCESS $FETCH dst,BLN,reg ;BLN field to 1-byte dst 

$COMPARE src,BLN,reg ; 1-byte src with BLN field 
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6.8.2 COD Field in SUM Block (XB$SUM Code) 

USE Contains the identifier for the SUM block. 
INIT None 
SIZE 1 byte 

ACCESS $FETCH dst,COD,reg ;COD field to 1-byte dst 

$COMPARE src,COD,reg ; 1-byte src with COD field 
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6.8.3 NOA Field in SUM Block 

USE Contains the number of areas in the file. 

INIT None 

SIZE 1 byte 

ACCESS $FETCH dst,NOA,reg ;NOA field to 1-byte dst 

$COMPARE src,NOA,reg ;l-byte src with NOA field 

OUTPUT DISPLAY Number of areas 
OPEN Number of areas 
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6.8.4 NOK Field in SDM Block 



OSE 
INIT 
SIZE 
ACCESS 

OOTPOT 



Contains the number of indexes in the file, 

None 

1 byte 



$FETCH dst,NOK,reg 
$COMPARE src,NOK,reg 



;NOK field to 1-byte dst 
;l-byte src with NOK field 



DISPLAY Number of indexes 
OPEN Number of indexes 
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6.8.5 NXT Field in SDM Block 



USE 

INIT 
SIZE 
ACCESS 

INPUT 



Contains the address of the next XAB (ALL, DAT, KEY, 
or SUM block) in a chain of XABs. 

X$NXT address 

1 word 



PRO, 



$FETCH dst,NXT,reg 
$STORE src,NXT,reg 
$COMPARE src,NXT,reg 



NXT field to 1-word dst 
1-word src to NXT field 
1-word src with NXT field 



CLOSE 


Next 


XAB 


address 


CREATE 


Next 


XAB 


address 


DISPLAY 


Next 


XAB 


address 


ENTER 


Next 


XAB 


address 


ERASE 


Next 


XAB 


address 


EXTEND 


Next 


XAB 


address 


OPEN 


Next 


XAB 


address 


PARSE 


Next 


XAB 


address 


REMOVE 


Next 


XAB 


address 


RENAME 


Next 


XAB 


address 


SEARCH 


Next 


XAB 


address 



6-150 



CONTROL BLOCK FIELDS 
SUM BLOCK SUMMARY 



6.8.6 PVN Field in SUM Block 



USE Contains the prologue version number for the file, 
INIT None 



SIZE 



ACCESS 



OUTPUT 



1 word 

$FETCH dst, PVN,reg ;PVN field to 1-word dst 
$COMPARE src,PVN,reg ;l-word src with PVN field 

DISPLAY Prologue version number 
OPEN Prologue version number 
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CHAPTER 7 
EXAMPLE PROGRAMS 



This chapter contains example programs; the titles of the programs 
are: 

• PARSE - $PARSE TEST 

• SEARCH - $SEARCH TEST 

• ERASE - $ERASE TEST 

• RENAME - $RENAME TEST 

• GSA - CORE SPACE ALLOCATOR 

Sections 7.1 through 7.4 contain these programs and give instructions 
for building and running them. 

NOTE 

References to [uic] in the command lines 
in the following sections indicate that 
you should include your default UIC. 

Each program requires the GSA routine (Section 7.5) for allocating 
dynamic memory: 

MAC SY:GSA=LB: [1, 1] RMSMAC/ML,SY: [uic] GSA 
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7.1 PARSE - $PARSE TEST 

The following shows how to build the PARSE program (Example 7-1) and 
shows a brief sample run of the program. 

MAG S¥sPARSE*LBs [1, 1] RMSMAC/ML, S¥: [ulc] PARSE 

TKB 

TKB>S¥ : PARSE/CP=S¥ : PARSE , S¥ : GSA 

TKB>LB: [1,1JVMLIB/LB:INIDM:EXTSK 

TKB>LB; [1,1]RMSLIB/LB 

TKB>// 

RUN DBl! [200,1] PARSE 

Enter the default name string: DBO : 

Enter the primary name string: .LOG 

$PARSE expanded string is DBO: [70,5] .LOG 

File name bits (FNB) are 004202 

(DEV, TYP) 
Enter the default name string: A Z 
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.TITLE 
. IDENT 



Example 7-1: PARSE - $PARSE Test 



PARSE - $PARSE TEST 
/X01.00/ 



. ENABL LC 

.MCALL FAB$B,NAM$B,GSA$ 

.MCALL $PARSE , $STORE , $FETCH , $COMPARE 

.MCALL ALUN$S,QIOW$,DIR$,EXIT$S 



This program tests/demonstrates the use of 
the RMS-11 $PARSE function. 



; RMS-11 Data Structures 



GSA$ 



GSA 



: : FAB$B 




F$NAM 


NAM 


F$LCH 


2. 


FAB$E 




: : NAM$B 




N$ESA 


EXPSTR 


N$ESS 


128. 


NAM$E 




.PSECT 


$CODE$,RO,I 


SE:: 

ALUN$S 


#1,#"TI,#0 


MOV 


#FAB,R0 


MOV 


#EDBLK,R2 


MOV 


#NAM,R3 


MOV 


#READ,R4 


MOV 


#WRITE,R5 


CLR 


Q.IOPL+4 (R5) 


MOV 


#QUES1,Q.I0PL(R5 


MOV 


#QUESlL,Q.I0PL+2 


DIR$ 


R5 


TSTB 


IOSTAT 


BMI 


EXIT 


MOV 


#BUFFl,Q.IOPL(R4 


MOV 


#64.,Q.IOPL+2(R4 


DIR$ 


R4 


TSTB 


IOSTAT 


BMI 


EXIT 


$STORE 


IOLEN,DNS,R0 


$STORE 


#BUFF1,DNA,R0 


MOV 


#QUES2,Q.IOPL(R5 


MOV 


#QUES2L,Q.IOPL+2 


DIR$ 


R5 


TSTB 


IOSTAT 


BMI 


EXIT 


MOV 


#BUFF2,Q.IOPL(R4 


MOV 


#64. ,O.IOPL+2(R4 


DIR$ 


R4 


TSTB 


IOSTAT 


BMI 


EXIT 



Argument FAB 
Link to NAM 
Channel #2 



NAM definition 
EXP STR address 
EXP STR length 



Assign the terminal 
Map the target FAB 
Map the exit block 
Map the target NAM 
Map the input DPB 
Map the output DPB 
Turn off carriage ctl 

R5) 
Prompt for the DNA 
Check the IOSB 
Exit if error 



Get the response 

Check the IOSB 

Exit if error 

Set the default length 

Set the default address 

R5) 
Prompt for the DNA 
Check the IOSB 
Exit if error 



Get the response 
Check the IOSB 
Exit if error 
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EXIT: 



ERROR: 



BITS: 



2$: 

4$: 

6$: 

8$: 

10$: 

12$: 

14$: 

16$: 

18$: 

20$: 

PRINT: 



$STORE 

$STORE 

MOV 

$PARSE 

$COMPARE 

BLT 

CLR 

$FETCH 

TST 

$FETCH 

$FETCH 

MOV 

CALL 

CALL 

BR 



EXIT$S 



$FETCH 

$FETCH 

MOV 

CALL 

BR 



MOV 

$FETCH 

BIT 

BEQ 

MOV 

BIT 

BEQ 

MOV 

BIT 

BEQ 

MOV 

BIT 

BEQ 

MOV 

BIT 

BEQ 

MOV 

BIT 

BEQ 

MOV 

BIT 

BEQ 

MOV 

BIT 

BEQ 

MOV 

BIT 

BEQ 

MOV 

BIT 

BEQ 

MOV 

MOV 

MOV 

CALL 

RETURN 



MOV 



IOLEN,FNS,R0 
#BUFF2,FNA,R0 
#40,Q.IOPL+4(R5) 
RO 

#0,STS f R0 
ERROR 

(R2) 

(R2) ,ESL,R3 

(R2) + 

(R2)+,ESA,R3 

(R2) ,FNB,R3 

#ESSSTR,R1 

PRINT 

BITS 

PARSE 



(R2)+,STS,R0 
(R2) ,STV,R0 
#ERRSTR,R1 
PRINT 
PARSE 

#EDBLK,R2 

R0,FNB,R3 

#2000, RO 

2$ 

#QUO,(R2)+ 

#1000, RO 

4$ 

#WDI,(R2)+ 

#400, RO 

6$ 

#NOD, (R2)+ 

#100, RO 

8$ 

#DIR, (R2)+ 

#40, RO 

10$ 

#WNA, (R2)+ 

#20, RO 

12$ 

#WTY, (R2)+ 

#10, RO 

14$ 

#WVE, (R2)+ 

#4,R0 

16$ 

#NME, (R2)+ 

#2,R0 

18$ 

#TYP, (R2)+ 

#1,R0 

20$ 

#VER, (R2)+ 

#END, (R2) 

#DEV,R1 

PRINT 



#EDBLK,R2 



Set the default length 

Set the default address 

Restore carriage control 

Parse the strings 

An error? 

Yes if MI; display it 

Init the length 

Get the string length 

Advance 

Get the string address 

Get the file name bits 

Select the format string 

Display the file 

Do the FNB bit disply 

And let's try another 



; Task exit 



Set the STS returned 

And the STV 

Set the error format string 

Go edit and print the message 

Let's try this again 



Init EDBLK address 

Get the FNB bits 

Quoted string? 

No if EQ 

Set Quoted string 

Wild directory? 

No if EQ 

Set wild directory 

Node spec? 

No if EQ 

Set nodespec 

Directory spec? 

No if EQ 

Set directory 

Wild name? 

No if eg 

Set wild name 

Wild type? 

No if EQ 

Set wild type 

Wild version? 

No if EQ 

Set wild version 

Name? 

No if EQ 

Set name 

Type? 

No if EQ 

Set type 

Version? 

No if EQ 

Set version 

End with a null... 

Set the default (dev) 

Edit and print 

And exit 



; Setup edit 
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MOV 

CALL 

MOV 

MOV 

DIR$ 

RETURN 



#BUFFER,R0 



; Output buffer 



$EDMSG ; Exit the string 

#BUFFER,Q.IOPL(R5) 
Rl,Q.IOPL+2 (R5) 

R5 ; Send to the terminal 

; Return to caller 



•PSECT $DATA$,RW,D 



QUES1: 


•Ascii 


<15><12>"Enter the default name string: 




QUES1L 


= . 


- QUES1 


QUES2: 


.Ascii 


<15><12>"Enter the primary name string: 




QUES2L 


= . 


- QUES2 


ERRSTR: 


.Asciz 


"$PARSE error — STS=%P, STV=%P" 


ESSSTR: 


.Ascii 


"$PARSE expanded string is %VA%N" 




•Asciz 


ii 


File name bits (FNB) are %P" 


DEV: 


•Asciz 


11 


(DEV%I" 


NOD: 


•Asciz 


■I 


NOD%I" 


DIR: 


•Asciz 


ii 


DIR%I" 


NME: 


•Asciz 


11 


NAM%I" 


QUO: 


•Asciz 


ii 

> 


QUO%I" 


TYP: 


•Asciz 


ii 


TYP%I" 


VER: 


•Asciz 


ii 


VER%I" 


WDI: 


•Asciz 


ii 


WDI%I" 


WNA: 


•Asciz 


H 


WNA% I " 


WTY: 


•Asciz 


ii 


WTY%I" 


WVE: 


•Asciz 


■1 


WVE%I" 


END: 


•Asciz 
• EVEN 


")' 


II 


EDBLK: 


• BLKW 


16. 




BUFFER: 








BUFFI: 


• Blkb 


64, 




BUFF2: 


• Blkb 


64 




EXPSTR: 


• BLKB 


128. 


IOSTAT: 


• WORD 







IOLEN: 


• WORD 







READ: 


QIOW$ 


10. 


•RLB, 1,1,, IOSTAT 


WRITE: 


QIOW$ 


10, 


.WLB, 1,1,, IOSTAT, ,<,,40> 



.END 



PARSE 
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7.2 SEARCH - $SEARCH TEST 

The following shows how to build the SEARCH program (Example 7-2) and 
shows a brief sample run of the program. 

MAC SY:SEARCH=LB: [1 , 1] RMSMAC/ML, SY: [uic] SEARCH 

TKB 

TKB>S Y : SEARCH/CP=SY : SEARCH , SY : GSA 

TKB>LB: [1,1]VMLIB/LB:INIDM:EXTSK 

TKB>LB: [1,1]RMSLIB/LB 

TKB>// 

RUN DB1: [200,1] SEARCH 

Enter a wildcard filespec: VHC*.* 



DBO 
DBO 
DBO 
DBO 
DBO 
DBO 
DBO 
DBO 
DBO 



[70,5]VHC.SEQ;1 

[70,5] VHC.INX;7 

[70,5]VHCKR0.DES;3 

[70,5] VHC. DES;2 

[70,5]VHC.MST;1 

[70,5]VHC.ERR;1 

[70,5]VHC.KR0;1 

[70,5]VHC.KR1;1 

[70,5]VHCKR0.INX;3 



Total of 9 files matching DBO: [70,5] VHC* .* 

Enter a wildcard filespec: [70 ,*] CUST.* 

DBO: [7O,"10]CUST.FILE;l 
DBO: [70,10]CUST.SEQ;1 
DBO: [70,5]CUST.MST;1 
DBO: [70,5]CUST.FIL;1 

Total of 4 files matching DBO: [70 ,*] CUST.* 

Enter a wildcard filespec: ~z 
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Example 7-2: SEARCH - $SEARCH Test 



.TITLE SEARCH - $SEARCH TEST 

. IDENT /X01.00/ 

. ENABL LC 

.MCALL FAB$B,NAM$B,GSA$ 

.MCALL $PARSE , $SEARCH , $STORE , $FETCH, $COMPARE 

.MCALL ALUN$S,QIOW$,DIR$,EXIT$S 



This program tests/demonstrates the use of 
the RMS-11 $SEARCH function. 



RMS-11 Data Structures 



GSA$ 



GSA 



FAB: : 



NAM: 



FAB$B 




F$DNA 


SYDSKA 


F$DNS 


SYDSKL 


F$NAM 


NAM 


F$LCH 


2. 


FAB$E 




NAM$B 




N$ESA 


EXPSTR 


N$ESS 


128. 


N$RSA 


RESSTR 


N$RSS 


128. 


NAM$E 





Argument FAB 
If no device, SY: 
should be used 
Link to NAM 
Channel #2 



NAM definition 
EXP STR address 
EXP STR length 
RES STR address 
RES STR length 



.PSECT $CODE$,RO,I 



SEARCH: : 




ALUN$S 


#1,#"TI,#0 


MOV 


#FAB,R0 


MOV 


#EDBLK,R2 


MOV 


#NAM,R3 


MOV 


#READ,R4 


MOV 


#WRITE,R5 


CLR 


Q.IOPL+4 (R5) 


MOV 


#QUES,Q.IOPL(R5) 


MOV 


#QUESL,Q.IOPL+2 ( 


DIR$ 


R5 


TSTB 


IOSTAT 


BMI 


EXIT 


MOV 


#BUFF,Q.IOPL(R4) 


MOV 


#64.,Q.IOPL+2 (R4 


DIR$ 


R4 


TSTB 


IOSTAT 


BMI 


EXIT 


$STORE 


IOLEN,FNS,R0 


$STORE 


#BCJFF,FNA,RO 


MOV 


#40, Q.IOPL+4 (R5) 


CLR 


FILCNT 


$PARSE 


R0 


$COMPARE #0,STS,RO 


BLT 


ERROR 


GETFIL: 





Assign the terminal 
Map the target FAB 
Map the exit block 
Map the target NAM 
Map the input DPB 
Map the output DPB 
Turn off carriage ctl 

R5) 

; Prompt for the DNA 
; Check the IOSB 
; Exit if error 



Get the response 

Check the IOSB 

Exit if error 

Set the string length 

Set the string address 

Restore carriage control 

Init count of matches 

Parse the strings 

An error? 

Yes if MI; display it 



7-7 



EXAMPLE PROGRAMS 



NOTFST; 



MOV #EDBLK,R2 
$SEARCH RO 
$COMPARE #0,STS,R0 



BLT 

CLR 

$FETCH 

TST 

$FETCH 

MOV 

TST 

BNE 

MOV 

CALL 
MOV 
INC 
BR 



ERROR 

(R2) 

(R2) ,RSL,R3 

(R2) + 

(R2)+,RSA,R3 

#RSSSTR,R1 

FILCNT 

NOTFST 

#RSSST1,R1 

PRINT 

#FAB,R0 

FILCNT 

GETFIL 



Reset the edit block addr 

Get a matching file 

Error? 

Yes if LT 

Init the length 

Get the string length 

Advance 

Get the string address 

Select the format string 

First file needs a blank 

line before it 

Insert CR/LF first 

Display the file 
Rest the FAB address 
Count this file 
And let's try another 



EXIT: 



EXIT$S 



Task exit 



ERROR: 



ERROR2: 



ERRORO: 



ERROR1: 



$COMPARE 

BNE 

MOV 

BEQ 

CLR 

$FETCH 

TST 

$FETCH 

MOV 

BR 

CLR 

$FETCH 

TST 

$FETCH 

MOV 

BR 

$FETCH 
$FETCH 
MOV 

CALL 
JMP 



#ER$NMF,STS,RO 
ERRORO 

FILCNT, (R2)+ 
ERROR2 

(R2) 

(R2) ,ESL,R3 

(R2) + 

(R2) ,ESA,R3 

#TTLSTR,R1 

ERROR1 

-(R2) 

(R2) ,ESL,R3 

(R2) + 

(R2) ,ESA,R3 

#NOFILE,Rl 

ERROR1 

(R2)+,STS,R0 
(R2) ,STV,R0 
#ERRSTR,R1 

PRINT 
SEARCH 



No more matches? 

No - some other error 

Set the cound of matches 

No files. . . 

Give the ESA 

Set the length 

Advance word 

Set the address 

Set the format string 

Go show it and exit 

Setup for string length 
Set the length 
Advance to next word 
Set the address 
Set the format string 
Print the error 

; Set the STS returned 

; And the STV 

; Set the error format string 

; Go edit and print the message 
; Let's try this again 



PRINT: 



MOV 

MOV 

CALL 

MOV 

MOV 

DIR$ 

RETURN 



#EDBLK,R2 

#BUFFER,R0 

$EDMSG 

#BUFFER,Q.IOPL(R5) 

Rl,Q.IOPL+2(R5) 

R5 



Setup edit 
Output buffer 
Exit the string 



Send to the terminal 
Return to caller 



.PSECT $DATA$,RW,D 

SYDSKA: .Ascii "SY:" 

SYDSKL = . - SYDSKA 

QUES: .Ascii <15><12>"Enter a wildcard filespec: " 

QUESL = . - QUES 

ERRSTR: .Asciz "$SEARCH error ~ STS=%P, STV=%P" 

RSSST1: .Ascii "%N" 

RSSSTR: .Asciz " %VA" 
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NOFILE: 


.Asciz 


"%NNo files matching %VA%N" 


TTLSTR: 


.Asciz 
.EVEN 


"%NTotal of %D files matching 


FILCNT: 


.WORD 





EDBLK: 


• BLKW 


6 


BUFFER: 






BUFF: 


.Blkb 


128. 


EXPSTR: 


.BLKB 


128. 


RESSTR: 


.BLKB 


128. 


IOSTAT: 


.WORD 





IOLEN: 


.WORD 





READ: 


QIOW$ 


10. RLB, 1,1,, IOSTAT 


WRITE: 


QIOW$ 


10. WLB, 1,1,, IOSTAT,, <,,40> 




.END 


SEARCH 



%VA%N" 
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7.3 ERASE - $ERASE TEST 

The following shows how to build the ERASE program (Example 7-3) and 
shows a brief sample run of the program. 

MAC SY:ERASE = LB: [ 1 , 1] RMSMAC/ML, SY: [uic]ERASE 

TKB 

TKB> SY : ERASE/CP=SY : ERASE , SY : GSA 

TKB> LB : [1,1] VML IB/LB : INIDM : EXTSK 

TKB>LB: [1,1] RMSLIB/LB 

TKB>// 

RUN DB1: [200,1]ERASE 

File(s) to erase: DES.XXX 

File DBO: [70,5]DES.XXX;3 deleted 

Total of 1 files matching DBO : [70,5] DES.XXX deleted 

File(s) to erase: ~Z 
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.TITLE 
, IDENT 



EXAMPLE PROGRAMS 



Example 7-3: ERASE - $ERASE Test 



ERASE - $ERASE TEST 
/X01.00/ 



. ENABL LC 

.MCALL FAB$B,NAM$B,GSA$ 

. MCALL $PARSE , $ERASE , $STORE , $FETCH , $COMPARE 

•MCALL ALUN$S,QIOW$,DIR$,EXIT$S 



This program tests/demonstrates the use of 

the RMS-11 $ERASE function, with implicit $SEARCH. 



RMS-11 Data Structures 



GSA$ 



GSA 



FAB: 



NAM: 



FAB$B 




Argument FAB 


F$DNA 


SYDSKA 


If no device, SY 


F$DNS 


SYDSKL 


• should be used 


F$NAM 


NAM 


Link to NAM 


F$LCH 


2. 


; Channel #2 


FAB$E 






NAM$B 




• NAM definition 


■N$ESA 


EXPSTR 


EXP STR address 


N$ESS 


128. 


; EXP STR length 


N$RSA 


RESSTR 


RES STR address 


N$RSS 


128. 


; RES STR length 


NAM$E 







.PSECT $CODE$,RO,I 



ERASE; 



ALUN$S 


#1,#"TI,#0 


MOV 


#FAB,RO 


MOV 


#EDBLK,R2 


MOV 


#NAM,R3 


MOV 


#READ,R4 


MOV 


#WRITE,R5 


CLR 


Q.IOPL+4 (R5) 


MOV 


#QUES,Q.IOPL(R5) 


MOV 


#QUESL,Q.IOPL+2( 


DIR$ 


R5 


TSTB 


IOSTAT 


BMI 


EXIT 


MOV 


#BUFF,Q.IOPL(R4) 


MOV 


#64.,Q.IOPL+2 (R4 


DIR$ 


R4 


TSTB 


IOSTAT 


BMI 


EXIT 


$STORE 


IOLEN,FNS,R0 


$STORE 


#BUFF,FNA,RO 


MOV 


#40,Q.IOPL+4(R5) 


CLR 


FILCNT 


$ PARSE 


RO 


$COMPARE #0,STS,R0 


BLT 


ERROR 


GETFIL: 





Assign the terminal 
Map the target FAB 
Map the exit block 
Map the target NAM 
Map the input DPB 
Map the output DPB 
Turn off carriage ctl 

R5) 

; Prompt for the DNA 
; Check the IOSB 
; Exit if error 



Get the response 

Check the IOSB 

Exit if error 

Set the string length 

Set the string address 

Restore carriage control 

Init count of matches 

Parse the strings 

An error? 

Yes if MI; display it 
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MOV 


#EDBLK,R2 


$ERASE 


RO 


$COMPARE #0,STS,R0 


BLT 


ERROR 


CLR 


(R2) 


$FETCH 


(R2) ,RSL,R3 


TST 


(R2) + 


$FETCH 


(R2)+,RSA,R3 


MOV 


#RSSSTR,R1 


TST 


FILCNT 


BNE 


NOTFST 


MOV 


#RSSST1,R1 


NOTFST: 




CALL 


PRINT 


MOV 


#FAB,R0 


INC 


FILCNT 


BR 


GETFIL 



Reset the edit block addr 

Issue implicit $ERASE 

Error? 

Yes if LT 

Init the length 

Get the string length 

Advance 

Get the string address 

Select the format string 

First file needs a blank 

line before it 

Insert CR/LF first 

Display the file 
Rest the FAB address 
Count this file 
And let's try another 



EXIT: 



EXIT$S 



; Task exit 



ERROR: 



$COMPARE #ER$NMF,STS,RO 



ERROR2: 



ERRORO: 



ERRORl: 



BNE 

MOV 

BEQ 

CLR 

$FETCH 

TST 

$FETCH 

MOV 

BR 

CLR 

$FETCH 

TST 

$FETCH 

MOV 

BR 

$FETCH 
$FETCH 
MOV 

CALL 
JMP 



ERRORO 

FILCNT, (R2)+ 

ERROR2 

(R2) 

(R2) ,ESL,R3 

(R2) + 

(R2) ,ESA,R3 

#TTLSTR,R1 

ERRORl 

-(R2) 

(R2) ,ESL,R3 

(R2) + 

(R2) ,ESA,R3 

#NOFILE,Rl 

ERRORl 

(R2)+,STS,R0 
(R2) ,STV,R0 
#ERRSTR,R1 

PRINT 
ERASE 



No more matches? 

No - some other error 

Set the cound of matches 

No files . . . 

Give the ESA 

Set the length 

Advance word 

Set the address 

Set the format string 

Go show it and exit 

Setup for string length 
Set the length 
Advance to next word 
Set the address 
Set the format string 
Print the error 

Set the STS returned 

And the STV 

Set the error format string 

Go edit and print the message 
Let's try this again 



PRINT: 



MOV 

MOV 

CALL 

MOV 

MOV 

DIR$ 

RETURN 



#EDBLK,R2 

#BUFFER,R0 

$EDMSG 

#BUFFER,Q.IOPL(R5) 

Rl,Q.IOPL+2(R5) 

R5 



Setup edit 
Output buffer 
Exit the string 



Send to the terminal 
Return to caller 



.PSECT $DATA$,RW,D 

SYDSKA: .Ascii "SY:" 

SYDSKL = . - SYDSKA 

QUES: .Ascii <15><12>"File (s) to erase: " 

QUESL = . - QUES 

ERRSTR: .Asciz "$ERASE error — STS=%P, STV=%P" 

RSSST1: .Ascii "%N" 

RSSSTR: .Asciz " File %VA deleted" 
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NOFILE: 


.Asciz 


"%NNo files matching %VA%N" 


TTLSTR: 


.Asciz 
.EVEN 


"%NTotal of %D files matching 


FILCNT: 


.WORD 





EDBLK: 


.BLKW 


6 


BUFFER: 






BUFF: 


.Blkb 


128. 


EXPSTR: 


.BLKB 


128. 


RESSTR: 


.BLKB 


128. 


IOSTAT: 


.WORD 





IOLEN: 


.WORD 





READ: 


QIOW$ 


IO.RLB, 1,1,, IOSTAT 


WRITE: 


QIOW$ 


10. WLB, 1,1,, IOSTAT, ,<, ,40> 




.END 


ERASE 



%VA deleted%N" 
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7.4 RENAME - $RENAME TEST 

The following shows how to build the RENAME program (Example 7-4) and 
shows a brief sample run of the program. 

MAC SY:RENAME=LB: [ 1 , 1] RMSMAC/ML , SY : [uic]RENAME 

TKB 

TKB>SY:RENAME/CP=SY:RENAME,SY:GSA 

TKB> LB :SYSL IB/LB: INIDM:EXTSK 

TKB>LB: [1,1]RMSLIB/LB 

TKB>// 

RUN DB1: [200 , 1] RENAME 

From: DES.TMP 

To: DES.XXX 

File DBO: [70,5]DES.TMP;3 renamed to DBO: [70,5]DES.XXX;3 

Total of 1 files matching DBO : [70,5] DES.TMP renamed 

From: ~Z 
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Example 7-4: RENAME - $RENAME Test 



.TITLE RENAME - $RENAME TEST 

, IDENT /X01.00/ 

•ENABL LC 

.MCALL FAB$B,NAM$B,GSA$ 

.MCALL SPARSE, $SEARCH,$RENAME,$STORE,$FETCH,$COMPARE 

.MCALL ALUN$S,QIOW$,DIR$,EXIT$S 



This program tests/demonstrates the use of 
the RMS-11 $RENAME function. 



RMS-11 Data Structures 



FAB1: 



NAM1: 



GSA$ 

FAB$B 
F$DNA 
F$DNS 
F$NAM 
F$LCH 
F$FOP 

FAB$E 

NAM$B 
N$ESA 
N$ESS 
N$RSA 
N$RSS 

NiAMSE 



GSA 



SYDSKA 

SYDSKL 

NAM1 

2. 

FB$FID 



ESSTR1 
128. 
RSSTR1 
128. 



Old file name 
Default to SY: 

Link to NAM1 

Channel #2 

Turn on NAM usage 



NAM definition 
EXP STR address 
EXP STR length 
RES STR address 
RES STR length 



FAB2: 



FAB$B 
F$NAM 
F$LCH 

FAB$E 



NAM 2 
2. 



New file name 
Link to NAM2 
Same channel 



NAM2 : : 



NAM$B 
N$ESA 
N$ESS 

NAM$E 



ESSTR2 
128. 



NAM definition 
EXP STR address 
EXP STR length 



•PSECT $CODE$,RO,I 



RENAME : 



ALUN$S 

MOV 

MOV 

MOV 

MOV 

CLR 

MOV 

MOV 

DIR$ 

TSTB 

BMI 

MOV 

MOV 



#1,#"TI,#0 

#FAB1,R0 

#EDBLK,R2 

#READ,R4 

#WRITE,R5 ; 

Q.IOPL+4(R5) ; 

#QUESl,Q.IOPL(R5) 

#QUESlL,Q.IOPL+2( 

R5 

IOSTAT ; 

EXIT ; 

#BUFFl,Q.IOPL(R4) 

#64. ,Q.IOPL+2(R4) 



Assign the terminal 
Map the target FAB 
Map the exit block 
Map the input DPB 
Map the output DPB 
Turn off carriage ctl 

R5) 
Prompt for the DNA 
Check the IOSB 
Exit if error 
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DIR$ 

TSTB 

BMI 

$STORE 

$STORE 

$ PARSE 



R4 

IOSTAT 

EXIT 

IOLEN,DNS,R0 

#BUFF1,DNA,R0 

RO 



$COMPARE #0,STS,R0 

BLT ERROR 

MOV #FAB2,R0 

MOV #QUES2,Q.IOPL(R5) 

MOV #QUES2L,Q.IOPL+2 ( 

DIR$ R5 ; 

TSTB IOSTAT ; 

BMI EXIT ; 

MOV #BUFF2,Q.IOPL(R4) 

MOV #64.,Q.IOPL+2(R4) 

DIR$ R4 

TSTB IOSTAT 

BMI EXIT 

$STORE IOLEN,FNS,R0 

$STORE #BUFF2,FNA,R0 

MOV #40,Q.IOPL+4 (R5) 

CLR FILCNT 

BR LOOP 



Get the response 

Check the IOSB 

Exit if error 

Set the default length 

Set the default address 

Parse the input spec 

An error? 

Yes if LT 

Map the 2d FAB 

R5) 
Prompt for the new name 
Check the IOSB 
Exit if error 



Get the response 
Check the IOSB 
Exit if error 
Set the default length 
Set the default address 
Restore carriage control 
Initialize file count 
Enter the RENAME loop 



EXIT: 



EXIT$S 



; Task exit 



LOOP: 



ERROR: 



MOV 


#FAB1,R0 


MOV 


#FAB2,R1 


MOV 


#NAM1,R2 


MOV 


#NAM2,R3 


$SEARCH 


RO 


$COMPARE #0,STS,R0 


BLT 


SEAERR 


$FETCH 


R4,RSA r R2 


$STORE 


R4,DNA,R1 


$FETCH 


R4,RSL,R2 


$STORE 


R4,DNS,R1 


$ RENAME 


R0,,,R1 


$COMPARE #0,STS,R0 


BLT 


ERROR 


MOV 


#EDBLK,R0 


CLR 


(RO) 


$FETCH 


(RO) ,RSL,R2 


TST 


(R0) + 


$FETCH 


(R0)+,RSA,R2 


CLR 


(RO) 


$FETCH 


(RO) ,ESL,R3 


TST 


(R0) + 


$FETCH 


(RO) ,ESA,R3 


MOV 


#RENMSG,R1 


CALL 


PRINT 


INC 


FILCNT 


BR 


LOOP 


MOV 


#EDBLK,R2 


$FETCH 


(R2)+,STS,R0 


$FETCH 


(R2) ,STV,R0 


MOV 


#ERRSTR,R1 


CALL 


PRINT 


JMP 


RENAME 



Get the input FAB 
And the output FAB 
Setup NAM references 

Attempt to find a file 

Error? 

Yes if LT 

Get the resultant address 

Set this as default 

Get the resultant length 

Set the default length 

Rename input as output 

Error? 

Yes if LT- investigate 

Setup to show the rename 

Set the length 
Advance to next word 
Set the address 

Set the length 

Advance to next word 

Set te address 

Format string 

Display it 

Count the file 

And try another file 



Map the edit block 

Set the STS returned 

And the STV 

Set the error format string 

Go edit and print the message 

Let's try this again 



SEAERR: 
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SETES: 



TOTAL: 



PRINT: 



$COMPARE #ER$NMF,STS,RO 

BNE ERROR 

MOV #EDBLK,R0 

TST FILCNT 

BNE TOTAL 

MOV #NOFILE,Rl 



CLR 

$FETCH 

TST 

$FETCH 

CALL 

JMP 

MOV 
MOV 
BR 



MOV 

MOV 

CALL 

MOV 

MOV 

DIR$ 

RETURN 



(RO) 

(RO) ,ESL,R2 

(R0) + 

(R0)+,ESA,R2 

PRINT 

RENAME 

FILCNT, (R0)+ 

#TTLMSG,R1 

SETES 



End of wild card search? 
No if NE- show why 
Map the edit block 
Any files? 

Yes if NE, show total 
Show the total 



Set the length 

Advance 

Get the ESA address 

Repeat 

Set the rename count 
Set the format string 
Add ESA and print 



#EDBLK,R2 ; Setup edit 
#BUFFER,R0 ; Output buffer 
$EDMSG ; Exit the string 

#BUFFER,WRITE+Q. IOPL 
Rl,WRITE+Q.IOPL+2 

#WRITE ; Send to the terminal 

; Return to caller 



.PSECT $DATA$,RW,D 

SYDSKA: .Ascii "SY:" 

SYDSKL = . - SYDSKA 

QUES1: .Ascii <15><12>"From: " 

QUES1L = . - QUES1 

QUES2: .Ascii <15><12>"To: " 

QUES2L = . - QUES2 

ERRSTR: .Asciz "$RENAME error — STS=%P, STV=%P" 

RENMSG: .Asciz " File %VA renamed to %VA" 

TTLMSG: .Asciz "%NTotal of %D files matching %VA renamed%N" 

NOFILE: .Asciz "%NNo files matching %VA%N" 

.EVEN 

FILCNT: .WORD 

EDBLK: .BLKW 6 
BUFFER: 

BUFFI: .BLKB 64. 

BUFF2: .BLKB 64 

ESSTR1: .BLKB 128. 

ESSTR2: .BLKB 128. 

RSSTR1: .BLKB 128. 

IOSTAT: .WORD 

IOLEN: .WORD 

READ: QIOW$ 10. RLB, 1,1,, IOSTAT 

WRITE: QIOW$ 10. WLB,1,1,, IOSTAT, ,<,,40> 



,END 



RENAME 
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7.5 GSA — CORE SPACE ALLOCATOR 



Example 7-5: GSA - Core Space Allocator 



.Title GSA - Core space allocator 
.Ident /V02.00/ 

, Enabl LC 



Copyright (C) 1982, Digital Equipment Corporation 

Maynard, Massachusetts 01754 

**-GSA - Dynamic memory allocation for RMS-11 pool 



Called by RMS-11 to manage v pool space. 
In the event of pool exhaustion, the task 
image will be extended to obtain more space. 

May be called by user written code providing 
the interface standard is adhered to. 

Interface : 

Request space: 

R0 -> RMS/user Pool list head (maintained by RL/CQB) 

Rl := AmoUnt of space requested (bytes) 

R2 := (differentiates between request and release) 

Release space: 

R0 -> RMS Pool list head (maintained by RL/CQB) 
Rl := Amount of space to be released (bytes) 
R2 -> Base address (for release) 



Returns: 

C-Bit "set" if an error has occurred (failure) 
C-Bit "clear" if no error has occurred (success) 



.Mcall Extk$S 

.Page 

.Sbttl Control block definitions 

.Psect GSA$$D,RW,D 



GSA internal data: 

GSABAS - Base address for the next memory allocation. 
Initially set to zero, it will be assigned 
the first address outside of the task's 
current address limits. 

GSAMIN - Decimal value reflecting the minimum size 
(in bytes) to extend the task in order to 
provide space to the pool. 

GSAREQ - Requested pool block number. If a request 
for the 'GSAMIN' fails, then the original 
allocation size will be attempted. If that 
fails, then there is no more memory left. 



7-18 



EXAMPLE PROGRAMS 



GSABAS : : 




.Word 


000000 


GSAMIN: : 




.Word 


512. /64 


GSAREQ: : 




.Word 


000000 



GSA base address 

(for next allocation) 

Minimum allocation 

(in 32-word blocks) 

Size of this request 

(if 'GSAMIN* extends fail) 



. Page 

.Sbttl GSA Initialization code 

.Psect GSA$$I,RO,I 



GSA Initialization 

This code is entered when GSA is entered with GSABAS 
set to zero. In order to be able to build valid pool 
header tables, GSABAS must be properly initialized and 
maintained. 

Initialization consists of finding the size of the task 
in 32-word units, and converting that value to a usable 
16-bit address (which corresponds to the address of the 
next task extension (Extk$S) call. Once GSABAS has been 
initialized, GSAINI will not be reused. 



GSAINI: 



Mov 
Mov 
Mov 



R0,-(SP) 
R1,-(SP) 
R2,-(SP) 



; R0-2 will be used to 
; communicate with $INIDM 
; NOTE: $INIDM uses EXTSK. 



The following code will use $INIDM to initialize the 
dynamic memory. As documented, Rl will return 
the first address following the task image, and R2 will 
return the size of the "free" memory from that address. 

NOTE: $INIDM and EXTSK reside in LB: [1, 1] VMLIB for RSX 
systems, and in LB:SYSLIB for RSTS/E systems. 

$INIDM interface: 
Calls: 

RO -> Pool list head 

Returns : 

R0 -> First address in task 

Rl -> First address AFTER task 

R2 := Size of free core after task (based at Rl) 



Call 


$INIDM ; 


Mov 


Rl, GSABAS ; 


Mov 


(SP)+,R2 ; 


Mov 


(SP)+,R1 ; 


Mov 


(SP)+,R0 


Return 




. Page 




.Sbttl 


GSA Mainline code 



Initialize dynamic memory 
Setup the "free" address 
Restore the registers 



And return to GSA 



Psect GSA$$M,RO,I 
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GSA Mainline 

Entry point is "GSA", with registers 0-2 loaded as 
described above. 



GSA: 



First, determine if dynamic memory has been initialized. 
GSABAS (initially set to zero) will be non-zero if $INIDM 
has been called and the memory list initialized. On RSX 
based systems it is possible to install tasks with an 
extension (/INCREMENT) . $INIDM will detect this and setup 
the first memory entry in the pool list. 

A point to note: If the RSX task has been installed with 
the non-checkpointable (/-CP) flag, then EXTKs will not 
return success. If it is necessary to install the task 
non-checkpointable, then the task should be installed with 
an increment value. 



Dynamic memory initialized? 
Yes if NE, proceed 
Otherwise, initialize pool 



Tst 


GSABAS 


Bne 


10$ 


Call 


GSAINI 



10$: 



Determine if this call involves real memory. 
Rl should contain the size (in bytes) of the core 
block requested or to be released. If zero then 
return to the caller without an error (TST leaves CC) 



Tst Rl 
Bne 20$ 
Return 



Real memory? 

Yes if NE, then process it 

Otherwise return with success 



20$: 



If this call is a request for space, pass control 
to the allocation routines. Otherwise, pass control 
to the system deallocation module $RLCB. There is 
no need to return, so control is passed via JMP. 
Note that module RQLCB resides in LB: [1, 1] SYSLIB 
for RSX11M/M-PLUS and LB:SYSLIB for RSTS/E. 



30$: 



Tst R2 
Beq 30$ 
Jmp $RLCB 



Address specified? (release) 
No if EQ, then it's a request 
Otherwise it's a release; do it 



Save our current context: 
R0 = Pool list head 
Rl = Size of memory required 
R2 = (signifies request) 



Mov 


R0,-(SP) 


Mov 


R1,-(SP) 


Mov 


R2,-(SP) 
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Attempt an allocation from the current pool 
If this is successful, pass control to the 
common exit. 



Call 
Bcc 



$RQCB 
70$ 



; Try the allocation 
; CC signifies success 



Now that the initial allocation failed, we must extend 
the task and give the new area (extended into) to the 
caller. To do this, the following procedure is used: 

1. The task is extended 

2. The area extended is returned to the 

pool specified as if a release was attempted 

3. We retry the allocation operation, but 
this time it should succeed, since we have 
increased the size of the pool area 

NOTE: $RQCB has a bad habit of nuking registers, so it 
becomes necessary to save and restore them around 
unsuccessful calls. 



Mov 



2(SP) ,R1 



Obtain the request size 



Determine what the requirement is in 32-word blocks, 
Retain this value to allow GSA to decide whether 
to issue further task extension directives in 
order to satisfy the requirements. 



Add 


#6 3.,R1 


Asr 


Rl ; 


Asr 


ri ; 


Asr 


ri ; 


Asr 


Rl 


Asr 


Rl 


Asr 


Rl 


Mov 


R1,GSAREQ ; 



Round the request 
to a 32-word boundary 
Then convert the value 
to the number of 
32-word blocks. 



Save the real size 



We will allocate core to the pool in "reasonable" 
increments to cut down on system overhead, and pool 
fragmentation. This is accomplished by using either 
the requested size, or "GSAMIN", whichever is LARGER. 
If the request is unsuccessful, and the amount is 
smaller than GSAMIN, then request that particular size 



Cmp 
Bhi 
Mov 



Rl, GSAMIN 
40$ 
GSAMIN, Rl 



; Smaller than minimum? 
; No if HI, use it as is 
; Otherwise use GSAMIN 



40$: 



Now we attempt to extend the task by that size. 
If the request fails, then use the size of the 
original request. If that also fails, then we 
simply ran out of memory. 



Extk$S Rl 



; Extend the task 
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50$: 



Bcc 


60$ 


Cmp 


R1,GSAREQ 


Bios 


50$ 


Mov 


GSAREQ,R1 


Br 


40$ 


Sec 




Br 


70$ 



; CC if successful 

; Is this request? 

; Yes if LOS, the end 

; Otherwise try to use 

; the actual request 

; Mark failure 

; And exit 



The task has been extended, now this memory must be 
released to the pool for future allocation. 
To do this, we setup the registers as if RMS were 
going to release the core, and call ourself to do 
the work. When the area has been released to the 
pool, we will return inline and proceed to reenter 
our code again from start to reattempt the allocation. 



60$; 



Mov 


4(SP) ,R0 


Asl 


Rl 


Asl 


Rl 


Asl 


Rl 


Asl 


Rl 


Asl 


Rl 


Asl 


Rl 


Mov 


GSABAS,R2 


Add 


R1,GSABAS 


Call 


GSA 



Setup the PLH 

Convert the real 

size to the actual 

16-bit size that 

was allocated. 

The virtual address 

should be after the 

task (which is now 

part of the task) 

Call ourself to release 



At this point, the new memory has been added to the 
pool, and is available for use. We now reattempt 
to allocate the memory required. 



Mov 
Mov 
Mov 
Br 



(SP)+,R2 
(SP)+,R1 
(SP)+,R0 
GSA 



; Restore our registers 

; to the initial state 

; upon entry, and reenter 

; as if it's a new request 



Common exit. Leave the registers in their current state, 
and return control to the caller. 



70$: 



Inc 
Bit 
Return 

• End 



(SP)+ ; These won't alter the 

(SP)+,(SP)+ ; C-bit, so status remains 
; unchanged upon return 
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APPENDIX A 
COMPLETION CODES AND FATAL ERROR CODES 



Section A.l describes RMS-11 completions that are returned in the STS 
and STV fields of FABs and RABs. Section A. 2 describes RMS-11 fatal 
error completions. 



A.l COMPLETIONS RETURNED IN STS AND STV FIELDS 

This section lists and explains RMS-11 completions that are returned 
in the STS and STV fields of FABs and RABs. For each completion, the 
symbol, message, octal and decimal values, and explanation are given. 



Octal : 
Decimal : 


000001 
1 


Octal: 
Decimal : 


000002 
2 



SU$SOC Operation succeeded 



SU$DUP Inserted record has duplicate key 



The PUT or UPDATE operation inserted a record whose key 
duplicates a key already in the index. Note that this 
completion may also be returned if a duplicate of some key in 
the new or updated record ever existed in the file, even if 
that key has since been changed or the record deleted. 

Octal: 000003 
Decimal: 3 



SU$IDX Error updating index 



The PUT or UPDATE operation inserted the record properly, but 
RMS-11 did not optimize the index structure; subsequent 
retrievals of the record will require extra I/O operations. 



ER$ACC File access error 



Octal: 177740 
Decimal: -32 



of 



1. A relative or indexed file is in the initial stage 
creation and cannot be accessed yet. 2. A write-accessed 
file was not properly closed. 3. The file processor could 
not access the file. The STV field of the FAB contains the 
file processor error code; see your operating system 
documentation for the meaning of the code. 

If the STV field contains a 0, the creation (or block access 
copy) of the relative or indexed file never completed. If the 
STV field contains a nonzero value, that value is a system 
error code indicating the reason the access was rejected. 
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ER$ACT Activity precludes operation Octal: 177720 

Decimal: -48 

RMS-11 could not perform the requested operation because of an 
activity in progress (for example, RMS-11 cannot perform the 
CLOSE operation for a file that has an outstanding 
asynchronous operation) . 

ERSAID Bad value in AID field Octal: 177700 

Decimal: -64 

The file contains no area with the area number given in the 
AID field of an ALL block. 

ER$ALN Bad mask in ALN field Octal: 177660 

Decimal: -80 

The ALN field of an ALL block contains an invalid value. 

ER$ALQ Bad value in ALQ field Octal: 177640 

Decimal: -96 

The ALQ field of a FAB or an ALL block contains an invalid 
value; the value in the ALQ field is either too large, or is 
for an EXTEND operation. 

ER$ANI Bad ANSI-format magtape file Octal: 177620 

Decimal: -112 

The records in an ANSI-format magtape file are 
variable-length, but are not in the proper ANSI-D format. 

ER$A0P Bad mask in AOP field Octal: 177600 

Decimal: -128 

The AOP field of an ALL block contains an invalid mask value. 

ER$ATR Error reading attributes Octal: 177540 

Decimal: -160 

The file processor could not read the attributes for the file. 

The STV field of the FAB or RAB contains the file processor 

error code; see your operating system documentation for the 
meaning of the code. 

ER$ATW Error writing attributes Octal: 177520 

Decimal: -176 

The file processor could not write the attributes for the 
file. The STV field of the FAB or RAB contains the file 
processor error code; see your operating system documentation 
for the meaning of the code. 

ER$BKS Bad value in BKS field 

The value in the BKS field of the FAB is t 
ER$BKZ Bad value in BKZ field 

The value in the BKZ field of an ALL block is too large; or 
the bucket sizes of the lowest (LAN) and upper (IAN) areas of 
an index are not equal. 
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Octal: 


177500 


Decimal : 


-192 


oo large. 




Octal : 


177460 


Decimal : 


-208 



COMPLETION CODES AND FATAL ERROR CODES 



ER$BOF Beginning-of-f ile found 



Octal: 177430 
Decimal: -232 



ER$BPA 



The SPACE operation backspaced to the beginning-of-f ile. 

Bad address in BPA field Octal: 

Decimal: 



177420 
-240 



The value in the BPA field of the FAB is odd, and the BPS 
field contains a nonzero value. 



ER$BPS Bad value in BPS field 



Octal : 
Decimal : 



177400 
-256 



The value in the BPS field of the FAB is nonzero and not a 
multiple of 4, and the BPA field is nonzero. 



ER$CCR RAB already in use 



Octal : 
Decimal 



177340 
-288 



The CONNECT operation could not connect a stream using the 
specified RAB because the file is sequential and does not 
allow multiple connected streams. 



ER$CHG Illegal record key change 



Octal: 
Decimal : 



177320 
-304 



The UPDATE operation did not allow a changed record key 
because the index does not allow key changes or does not allow 
duplicate key values. 



ER$CHK Bad bucket header 



Octal : 
Decimal : 



177300 
-320 



The bucket header data for an indexed file is corrupted. 

Notify your system manager, who should follow this procedure 
to recover from the error: 

1. Move the disk to a different drive and try the process 
again. If the process succeeds, the error was a hardware 
error; report the faulty hardware and continue 
processing. If the process fails again, proceed to the 
next step. 

2. Recreate the file using an RMS-11 utility (RMSIFL or 
RMSCNV) . If this succeeds, the primary index and data 
records were free of errors and the new file is valid; 
continue processing. If this fails, proceed to the next 
step. 



ER$CLS 



3. Restore the file from a backup copy. 
File processor error 



Octal: 177260 
Decimal: -336 



The file processor returned an error condition to the CLOSE 
operation. The STV field of the FAB contains the file 
processor error code; see your operating system documentation 
for the meaning of the code. 



ER$COD \Bad co^e in COD field 

The value in the COD field of an XAB is not valid. 



Octal: 177240 
Decimal: -352 
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ER§CRE File processor error Octal: 177220 

Decimal: -368 

The file processor returned an error condition to the CREATE 
operation. The STV field of the FAB contains the file 
processor error code; see your operating system documentation 
for the meaning of the code. 

ERSCUR Undefined current-record context Octal: 177200 

Decimal: -384 

A DELETE, TRUNCATE, or UPDATE operation required a defined 
current-record context, but it was undefined. 

ER$DAN Bad value in DAN field Octal: 177140 

Decimal: -416 

The value in the DAN field of a KEY block specifies a 
nonexistent area. 

ER$DEL Record having RFA deleted Octal: 177120 

Decimal: -432 

The record specified by RFA has been deleted. 

ER$DEV Bad device specification Octal: 177100 

Decimal: -448 

The device specification given contains a syntax error, there 
is no such device, the device is inappropriate for the 
operation, or two different devices have been specified for a 
RENAME operation. 

ER$DFW File processor error Octal: 177070 

Decimal: -456 

The file processor returned an error while writing 
deferred-write data. The STV field of the FAB or RAB contains 
the file processor error code; see your operating system 
documentation for the meaning of the code. 

ER$DIR Bad directory specification Octal: 177060 

Decimal: -464 

The directory specification contains a syntax error. 

ER$DME Pool exhausted Octal: 177040 

Decimal: -480 

One of the five pools that RMS-11 uses cannot provide needed 
space for the operation. 

ER$DNA Bad address in DNA field Octal: 177030 

Decimal: -488 

The DNA field of the FAB contains 0, but the DNS field is 
nonzero. 

ER$DNF No such directory Octal: 177020 

Decimal: -496 

The directory specification given specifies a nonexistent 
directory. 
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ER$DNR Device not ready 



The device specified is not on line. 
ER$DPE Device positioning error 



Octal: 177000 
Decimal: -512 



Octal: 176770 
Decimal: -520 



The file processor could not position the magtape device as 
specified. The STV field of the FAB or RAB contains the file 
processor error code; see your operating system documentation 
for the meaning of the code. 



ER$DTP Bad code in DTP field 



Octal: 176760 
Decimal: -528 



The value in the DTP field of a KEY block does not specify a 
valid key data type. 



ER$DUP Duplicate key not allowed 



Octal: 176740 
Decimal: -544 



The record offered for insertion had a record key that would 
duplicate a record already in the index, but the index does 
not allow duplicate keys. 



ER$ENT File processor error 



Octal: 176720 
Decimal : -560 



The file processor could not create the specified directory 
entry. The STV field of the FAB contains the file processor 
error code; see your operating system documentation for the 
meaning of the code. 



ER$ENV Feature not in selected RMS-11 environment 



Octal: 176700 
Decimal: -576 



The RMS-11 environment (selected with the ORG$ macro or by the 
compiler or by the manner in which RMS-11 code is linked with 
your program) does not include the attempted operation for the 
specified file organization. 



ER$EOF End-of-file reached 



Octal: 176660 
Decimal: -592 



The operation specified a record or block that is past the 
last record or block. 



ER$ESA Bad address in ESA field 

The ESA field of the NAM block contains 0. 
ER$ESL Bad value in ESL field 

The ESL field of the NAM block contains 0. 
ER$ESS ESS field value too small 



Octal : 
Decimal : 



Octal : 
Decimal : 



Octal: 
Decimal: 



176650 
-600 



176644 
-604 



176640 
-608 



The value in the ESS field of the NAM block specifies an 
expanded string buffer that is too small to contain the 
expanded string. 
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ER$EXP File expiration date not yet reached 



Octal: 176630 
Decimal: -616 



ER$EXT File processor error 



Octal: 176620 
Decimal: -624 



The file processor could not make the requested extension to 
the file. The STV field of the FAB or RAB contains the file 
processor error code; see your operating system documentation 
for the meaning of the code. 



ER$FAC FAC field forbids operation 



Octal: 176560 
Decimal: -656 



The attempted record or block operation was not specified in 
the FAC field of the FAB when the file was created or opened. 



ER$FAL Operation not supported by remote node 



Octal: 176550 
Decimal : -664 



The remote node for a remote RMS-11 operation does not support 
hat operation. The STV field of the FAB or RAB contains (in 
ts high 4 bits) a code that gives the reason for the error: 

— Incompatible operating systems; the low 12 bits of the 
STV field contain the type of the remote operating system 

1 — Incompatible file systems; the low 12 bits of the STV 
field contain the type of the remote file system 

2 — DAP version number smaller than 5; the low 12 bits of 
the STV field contain the DAP version number 

3 — DAP modification number smaller than 6; the low 12 bits 
of the STV field contain the DAP modification number 

4 — Unsupported file organization 

5 — Unsupported record access 

6 — Operation not supported by FAL; the low 12 bits of the 
STV field contain the operation code 

7 — Remote I/O buffer too small; the low 12 bits contain 
the size of the remote I/O buffer 



ER$FEX File already exists 



Octal: 176540 
Decimal: -672 



The file specified for creation already exists, but 
supersession was not specified. 



ER$FID Bad value in FID field 



Octal: 177530 
Decimal: -680 



The FID field of the NAM block contains a value that is not a 
file identifier. 



ER$FLG Bad mask in FLG field 



Octal: 176520 
Decimal: -688 



The combination of masks specified in the FLG field of a KEY 
block is illegal. 
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ER$FLK File locked by another task 



Octal: 176500 
Decimal: -704 



The file sharing specified is not allowed by a task already 
accessing the file. 



ER$FNA Bad address in FNA field 



Octal: 176470 
Decimal: -712 



The FNA field of the FAB contains 0, but the FNS field is 
nonzero. 



ER$FND File processor error 



Octal: 176460 
Decimal: -720 



The file processor could not find the file specified. The STV 
field of the FAB contains the file processor error code; see 
your operating system documentation for the meaning of the 
code. 



ER$FNF File not found 



Octal: 176440 
Decimal: -736 



The file specified for a directory or file operation does not 
exist. 



ER$FNM Bad file name 



Octal:, 176420 
Decimal: -752 



The file name portion of a file specification string has a 
syntax error. 



ER$FOP Bad mask in FOP field 



Octal : 
Decimal : 



176400 
-768 



The FOP field of the FAB contains one or more illegal masks 
ER$FDL Device or file full 



Octal: 176360 
Decimal: -784 



The specified device or file has no room to allow file 
creation or extension. 



ER$IAN Bad value in IAN field 



Octal: 176340 
Decimal: -800 



The value in the IAN field of a KEY block specifies a 
nonexistent file area. 



ER$IDX Index not initialized 



Octal: 176320 
Decimal: -816 



This code is only returned in the STV field of the RAB in 
conjunction with the code ER$RNF in the STS field. It 
indicates that no entries have been made in the index 
specified for the GET or FIND operation. 



ER$IFI Bad value in IFI field 



Octal: 176300 
Decimal: -832 



The value in the IFI field of the FAB is not the internal file 
identifier for a file. 
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ER$IMX Too many XABs of same type Octal: 176260 

Decimal: -848 

The number of XABs of the same type in the chain of XABs is 
too large (more than 254 ALL blocks or KEY blocks, more than 1 
DAT block, PRO block, or SUM block). 

ER$IOP Illegal operation for file Octal: 176220 

Decimal: -880 

The requested operation is illegal for the file organization 
or for the allowed access. 

ER$IRC Illegal record found in sequential file Octal: 176200 

Decimal: -896 

The record length field of a record in a sequential file is 
invalid . 

ER$ISI Bad value in ISI field Octal: 176160 

Decimal: -912 

The ISI field of the RAB contains a value that is not an 
internal stream identifier. 

ER$KBF Bad address in KBF field Octal: 176140 

Decimal: -928 

The KBF field of the RAB contains 0. 

ER$KEY Bad key Octal: 176120 

Decimal: -944 

The key specified for a key access operation is invalid 
(either a negative RRN or an erroneous packed-decimal key) . 

ER$KRF Bad value in KRF field Octal: 176100 

Decimal: -960 

The KRF field of the RAB contains (or contained) a value that 
does not specify a file index. For a key access FIND or GET 
operation, the RAB contains the invalid value in its KRF 
field; for a sequential access FIND or GET operation, the RAB 
contained the invalid value in its KRF field during an earlier 
CONNECT or REWIND operation. 

ER$KSZ Bad value in KSZ field Octal: 176060 

Decimal: -976 

The KSZ field of the RAB contains an invalid value. 

ER$LAN Bad value in LAN field Octal: 176040 

Decimal: -992 

The value in the LAN field of a KEY block specifies a 
nonexistent file area. 

ER$LBL Bad magtape label Octal: 176020 

Decimal: -1008 

The magtape does not have a valid ANSI label. 
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ER$LBY Logical channel busy 



Octal: 176000 
Decimal: -1024 



The LCH field of the FAB contains the number of a logical 
channel that is already in use by the task. 



ER$LCH Bad value in LCH field 



Octal: 175760 
Decimal: -1040 



The LCH field of the FAB contains a value that is too large to 
be a logical channel number. 



ER$LEX Extension not needed 



Octal: 175750 
Decimal: -1048 



The requested extension was not needed because the file area 
still contains an unused extent. 



ER$LOC Bad value in LOC field 



Octal: 175740 
Decimal: -1056 



The LOC field of an ALL block contains a value that does not 
specify a valid location. 



ER$MEM Memory address rollover 



Octal: 175710 
Decimal: -1080 



The area specified for the file string, default string, 
expanded string, or resultant string extends beyond the end of 
addressable memory. 



ER$MKD File processor error 



Octal : 175700 
Decimal: -1088 



ER$MRN 



The file processor could not mark the specified file for 
deletion. The STV field of the FAB contains the file 
processor error code; see your operating system documentation 
for the meaning of the code. 

Bad value in MRN field or bad record number Octal: 175660 

Decimal : -1104 



The MRN field of the FAB contains a negative number (CREATE 
operation), or the record number specified for a key access 
record operation is larger than the file maximum record number 
(specified in the MRN field at file creation) . 



ER$MRS Bad value in MRS field 



Octal: 175640 
Decimal: -1120 



The MRS field of the FAB contains even though the file to be 
created is requested either to be a relative file or to have 
fixed-length records. 



A-9 



COMPLETION CODES AND FATAL ERROR CODES 

ER$NAE Onmappable network access error Octal: 175630 

Decimal: -1128 

If this error occurs, please submit a Software Performance 
Report to DIGITAL, including the following information: 

• Contents of general registers and stack 

• Operation and file organization for which the error 
occurred 

• Task builder map of the task 

• Post-mortem dump 

ER$NAM Bad address in NAM field Octal: 175620 

Decimal: -1136 

The NAM field of the FAB contains or an odd address. 

ER$NEF Context not end-of-file Octal: 175600 

Decimal: -1152 

The PUT operation could not insert a record into a sequential 
file because the next-record context was not the end-of-file. 

ER$NET Network link lost Octal: 175570 

Decimal: -1160 

The STV field of the FAB or RAB contains the network error 
code . 

ER$NMF No more matching files Octal: 175554 

Decimal: -1172 

The SEARCH operation ended the wildcard SEARCH series because 
there are no more files matching the wildcard file 
specification. 

ER$NOD Bad node name Octal: 175550 

Decimal: -1176 

The specified node name is invalid or, for the RENAME 
operation, the two node names are different. 

ER$NPK No primary key for indexed file Octal: 175540 

Decimal: -1184 

The CREATE operation did not create the specified file because 
no primary index was specified even though the request 
specified indexed file organization. 

ER$ORD Ordering of XABs illegal Octal: 175500 

Decimal: -1216 

The chain of XABs for a directory or file operation is 
improperly ordered. 

ER$ORG Bad mask in ORG field Octal: 175460 

Decimal: -1232 

The ORG field of the FAB contains an invalid file organization 
code; the file was not created. 
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ER$PLG Error reading file prologue 



Octal: 175440 
Decimal: -1248 



The data read from the file prologue is incorrect. 

Notify your system manager, who should follow this procedure 
to recover from the error: 

1. Move the disk to a different drive and try the process 
again. If the process succeeds, the error was a hardware 
error; report the faulty hardware and continue 
processing. If the process fails again, proceed to the 
next step. 

2. Recreate the file using an RMS-11 utility (RMSIFL or 
RMSCNV) . If this succeeds, the primary index and data 
records were free of errors and the new file is valid; 
continue processing. If this fails, proceed to the next 
step. 



3. Restore the file from a backup copy. 
ERSPLV File prologue version level unsupported 



Octal: 175430 
Decimal: -1256 



The file prologue version number shows that the file was 
created by a version of RMS that is not supported on your 
system. 



ER$P0S Bad value in POS field 



Octal: 175420 
Decimal: -1264 



The POS field of a KEY block contains a value that is greater 
than the maximum record size for the file; the STV field of 
the FAB contains the address of the KEY block. 



ER$PRM Bad file date read 

The file dates read are illegal, 
ER$PRV Privilege violation 



Octal : 
Decimal : 



Octal: 
Decimal : 



175400 
-1280 



175360 
-1296 



The file processor denied the requested operation because the 
task has no privilege for the operation. 



ER$RAC Bad mask in RAC field 



Octal: 
Decimal : 



The RAC field of the RAB contains an illegal value 
ER$RAT Bad mask in RAT field 



Octal: 
Decimal : 



ER$RBF 



The RAT field of the FAB contains illegal set bits. 
Bad address in RBF field 



Octal : 
Decimal : 



175320 
-1328 



175300 
-1344 



175260 
-1360 



The RBF field of the RAB contains an odd address; the address 
must be even for block access. 
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ER$RER File processor error Octal: 175240 

Decimal: -1376 

The file processor could not read the requested record or 
block. The STV field of the FAB or RAB contains the file 
processor error code; see your operating system documentation 
for the meaning of the code. 

ERSREX Record already exists Octal: 175220 

Decimal : -1392 

The target cell for a PUT operation to a relative file already 
contains a record. 

ER$RFA Bad value in RFA field Octal: 175200 

Decimal: -1408 

The RFA field of the RAB contains an illegal RFA. 

ER$RFM Bad code in RFM field Octal: 175160 

Decimal: -1424 

The RFM field of the FAB contains an illegal value. 

ER$RLK Record locked Octal: 175140 

Decimal: -1440 

The bucket containing the specified record is locked by 
another task or by another stream in your task. 

ERSRMV File processor error Octal: 175120 

Decimal: -1456 

The file processor could not delete the specified directory 
entry. The STV field of the FAB contains the file processor 
error code; see your operating system documentation for the 
meaning of the code. 

ER$RNF No such record Octal: 175100 

Decimal: -1472 

The record specified for key access does not exist. 

ER$RNL Record not locked Octal: 175060 

Decimal: -1488 

The FREE operation found that no record was locked for the 
stream. 

ER$ROP Bad mask in ROP field Octal: 175040 

Decimal: -1504 

The ROP field of the RAB contained illegal set bits. 
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ER$RPL File processor error Octal: 175020 

Decimal: -1520 

The data read from the file prologue is incorrect. 

Notify your system manager, who should follow this procedure 
to recover from the error: 

1. Move the disk to a different drive and try the process 
again. If the process succeeds, the error was a hardware 
error; report the faulty hardware and continue 
processing. If the process fails again, proceed to the 
next step. 

2. Recreate the file using an RMS-11 utility (RMSIFL or 
RMSCNV). If this succeeds, the primary index and data 
records were free of errors and the new file is valid; 
continue processing. If this fails, proceed to the next 
step. 

3. Restore the file from a backup copy. 

ER$RRV Bad internal pointer Octal: 175000 

Decimal : -1536 

An internal pointer in the file is invalid. Reload the file, 
with RMSCNV or RMSIFL, using its primary index. 

ER$RSL Bad value in RSL field Octal: 174754 

Decimal: -1556 

The RSL field of the NAM block contains 0. 

ER$RSS Bad value in RSS field Octal: 174750 

Decimal: -1560 

The RSS field of the NAM block contains 0. 

ER$RST Bad address in RSA field Octal: 174744 

Decimal: -1564 

The RSA field of the NAM block contains 0. 

ER$RSZ Bad value in RSZ field Octal: 174740 

Decimal: -1568 

The RSZ field of the RAB contains a value that is larger than 
the maximum allowed record size, or (for fixed-length records) 
is not equal to the maximum record size, or (for an UPDATE 
operation to a sequential file) is not equal to the length of 
the record to be updated. 

ER$RTB Record too big for user buffer Octal: 174720 

Decimal: -1584 

The record read cannot fit into the user buffer; the STV 

field of the RAB contains the size of the record, and the 

portion that will fit is moved to the user buffer as for a 
successful GET. 
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ER$RVC Internal pointer corrupted Octal: 174710 

Decimal: -1592 

The record insertion succeeded and the primary index was 
updated successfully; however, RMS-11 could not update 
internal pointers. 

To recover from the error, follow this procedure: 

1. Recreate the file using an RMS-11 utility (RMSIFL or 
RMSCNV) . If this succeeds, the primary index and data 
records were free of errors and the new file is valid; 
continue processing. If this fails, proceed to the next 
step. 

2. Restore the file from a backup copy. 

ER$SEQ Sequential insertion records not in order Octal: 174700 

Decimal: -1600 

The sequential access PUT operation found records whose 
primary keys were not in ascending order. 

ER$SHR Bad mask in SHR field Octal: 174660 

Decimal: -1616 

The SHR field of the FAB contains an illegal mask. 

ER$SIZ Bad value in SIZ field Octal: 174640 

Decimal: -1632 

The SIZ field of a KEY block contains an illegal value. 

ER$SUP Operation not supported over network Octal: 174610 

Decimal: -1656 

The requested operation is not supported over the network. 

ER$SYS System error Octal: 174600 

Decimal: -1664 

The interface between RMS-11 and the system is in error; the 
STV field of the FAB or RAB contains the status code for a 
system directive. Please submit a Software Performance 
Report. 

ER$TRE Index error Octal: 174560 

Decimal: -1680 

The index contains invalid data. Build a new file using 
either an RMS-11 utility (RMSIFL or RMSCNV) or using 
sequential access and the primary index to fetch the old 
records. 

ER$TYP Bad file type Octal: 174540 

Decimal: -1696 

The file type in a file specification contains invalid syntax. 

ER$UBF Bad address in DBF field Octal: 174520 

Decimal: -1712 

The UBF field of the RAB contains or, for block access, an 
odd address. 
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ERSUIN Field value rejected by FAL 



Octal: 174510 
Decimal: -1720 



The FAL (file access listener) rejected the value in a control 
block field; the STV field of the FAB or RAB contains a code 
showing which field. See your DECnet documentation for the 
meanings of these codes. 



ER$0SZ Bad value in USZ field 

The USZ field of the RAB contains 0. 
ER$VER Bad file version number 



Octal : 
Decimal: 



Octal : 
Decimal : 



174500 
-1728 



174460 
-1744 



The file version portion of a file specification contains a 
syntax error. 



ER$WCD Illegal wildcard in merged string 



Octal: 174430 
Decimal: -1768 



The merged string contains a wildcard character, but 
wildcarding is not in progress or is illegal for the 
operation. 



ER$WER File processor error 



Octal: 174420 
Decimal: -1776 



The file processor could not write to the file. The STV field 
of the FAB or RAB contains the file processor error code; see 
your operating system documentation for the meaning of the 
code. 



ER$WLK Device write-locked 

The device specified is write-locked. 
ER$WPL File processor error 



Octal: 
Decimal; 



Octal : 
Decimal : 



174410 
-1784 



174400 
-1792 



The file processor could not write the file prologue. The STV 
field of the FAB or RAB contains the file processor error 
code; see your operating system documentation for the meaning 
of the code. 



ER$XAB Bad address in XAB field 



Octal: 
Decimal : 



The XAB field of the FAB contains an odd address. 



ER$XTR Extraneous data in file specification 



Octal : 
Decimal 



174360 
-1808 



174340 
-1824 



The file specification contains extraneous characters. The 
value in the STV field of the FAB is the address of the first 
character beyond the end of the valid file specification. 
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A. 2 FATAL ERROR COMPLETIONS 



This section lists and explains RMS-11 completions that are returned 
in general register RO. These errors are fatal either because RMS-11 
detected an internal error condition and could not continue, or 
because the RAB or FAB is of questionable validity and RMS-11 
therefore did not write the completion in its fields. 



ER$ACT Illegal concurrent operation 



Octal: 177720 
Decimal : -48 



1. The FAB you specified is already in use by another 
operation. 2. You have illegally interrupted RMS-11 
processing. 



ER$AST Illegal operation at AST level 



Octal: 177560 
Decimal: -144 



Your program attempted to use WAIT operation at AST level. 

ER$BOG Error in RMS-11 internal data Octal: 177360 

Decimal: -272 

RMS-11 detected an error in its internal data structures. The 
error may have been caused by your task writing into the 
structures; if you think your task did not cause the error, 
please submit a Software Performance Report to DIGITAL, 
including the following information: 

• Contents of general registers and stack 

• Operation and file organization for which the 
occurred 

• Task builder map of Hr» task 

• Post-mortem dump 
Bad parameter block 



error 



ER$CPB 



Octal : 
Decimal : 



177230 
-360 



The parameter block (pointed to by R5) for an operation macro 
has an invalid argument count or is at a zero or odd address. 



ER$FAB Bad FAB 



Octal: 176600 
Decimal: -640 



The value in the BID or BLN field of the specified FAB is not 
the correct identifier or block length for a FAB, or the 
address of the FAB is or odd. 



ER$LIB Resident library not available 



Octal: 175744 
Decimal: -1052 



The version of the RMS-11 resident library needed for your 
task is not available. 
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ER$MAP Error in internal buffer mapping data Octal: 175720 

Decimal: -1072 

RMS-11 detected an error in its internal data structures. The 
error may have been caused by your task writing into the 
structures; if you think your task did not cause the error, 
please submit a Software Performance Report to DIGITAL, 
including the following information: 

• Contents of general registers and stack 

• Operation and file organization for which the error 
occurred 

• Task builder map of the task 

• Post-mortem dump 

ER$RAB Bad RAB Octal: 175340 

Decimal: -1312 

The value in the BID or BLN field of the specified RAB is not 
the correct identifier or block length for a RAB, or the 
address of the RAB is or odd. 
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RMS-11 macros detect some errors during assembly. For each such 
error, the macro issues a .PRINT or .ERROR assembler directive with a 
message. This appendix shows these messages and their meanings. 

$COMPARE MACRO - FIELD TOO LARGE 

You can specify only a 1-byte or 1-word field as the field 
parameter for the $COMPARE macro. 

$COMPARE MACRO - FIELD PARAMETER INVALID 

You must specify a valid field mnemonic as the field parameter 
for the $COMPARE macro. 

$FETCH MACRO - PC DESTINATION INVALID 

You cannot specify the PC as the destination for the $FETCH 
macro. 

$FETCH OR $STORE MACRO - ADDRESS MODE INVALID 

You have used an illegal address mode in the source for a $STORE 
macro or in the destination for a $FETCH macro. See Chapter 3 
for a description of legal address modes for these macros. 

$FETCH OR $STORE MACRO - FIELD PARAMETER INVALID 

You can specify only a valid field mnemonic as the field 
parameter for a field access macro. 

$FETCH OR $STORE MACRO - FIELD TOO LARGE FOR GIVEN REGISTERS 

You cannot specify the given register as the source or 
destination address because the field is larger than the 
remaining registers. 

$FETCH OR $STORE MACRO - FIELD TOO LARGE FOR IMMEDIATE MODE 

You can specify an immediate mode value for a field access macro 
only if you specify a 1-byte or 1-word field. 

$FETCH OR $STORE MACRO - FIELD TOO LARGE FOR REGISTERS 

You cannot specify a register as the source or destination 
address because the given field is too large. 
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$FETCH OR $STORE MACRO - REGISTER PARAMETER INVALID 

You can specify only RO, Rl, R2, R3, R4, or R5 as the register 
parameter for a field access macro. 

$FETCH OR $STORE MACRO - REGISTER USAGES OVERLAP 

You cannot specify the given register as the source or 
destination address because the indicated registers overlap the 
register containing the control block address. 

$OFF MACRO - FIELD TOO LARGE 

You can specify only a 1-byte or 1-word field as the field 
parameter for the $OFF macro. 

$OFF MACRO - FIELD PARAMETER INVALID 

You must specify a valid field mnemonic as the field parameter 
for the $OFF macro. 

$SET MACRO - FIELD TOO LARGE 

You can specify only a 1-byte or 1-word field as the field 
parameter for the $SET macro. 

$SET MACRO - FIELD PARAMETER INVALID 

You must specify a valid field mnemonic as the field parameter 
for the $SET macro. 

$SETGSA MACRO - REGISTER PARAMETER INVALID 

You must specify RO, Rl, R2, R3, R4, or R5 as the register 
parameter for the $SETGSA macro. 

$TESTBITS MACRO - FIELD TOO LARGE 

You can specify only a 1-byte or 1-word field as the field 
parameter for the $TESTBITS macro. 

$TESTBITS MACRO - FIELD PARAMETER INVALID 

You must specify a valid field mnemonic as the field parameter 
for the STESTBITS macro. 

F$BSZ MACRO - BSZ FIELD NOT USED IN RMS-11 

RMS-11 has no BSZ field in the FAB; therefore the F$BSZ macro 
cannot initialize the field. 

F$JFN MACRO - JFN FIELD NOT USED IN RMS-11 

RMS-11 has no JFN field in the FAB; therefore the F$JFN macro 
cannot initialize the field. 

FAB$B MACRO - ALREADY IN BLOCK OR POOL DECLARATION 

You cannot use the FAB$B macro to begin FAB declaration until you 
have ended the current block or pool declaration (using the 
FAB$E, NAM$E, POOL$E, RAB$E or XAB$E macro) . 

FAB$B MACRO - FAB NOT WORD-ALIGNED 

Use the .EVEN assembler directive before the FAB$B macro; this 
assures word-alignment for the FAB. 
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FAB$E MACRO - NOT IN FAB DECLARATION 

You must begin a FAB declaration with the FAB$B macro before 
ending it with a FAB$E macro. 

NAM$B MACRO - ALREADY IN BLOCK OR POOL DECLARATION 

You cannot use the NAM$B macro to begin NAM block declaration 
until you have ended the current block or pool declaration (using 
the FAB$E, NAM$E, PO0L$E, RAB$E or XAB$E macro) . 

NAM$B MACRO - NAM BLOCK NOT WORD-ALIGNED 

Use the .EVEN assembler directive before the NAM$B macro; this 
assures word-alignment for the NAM. 

NAM$E MACRO - NOT IN NAM BLOCK DECLARATION 

You must begin a NAM block declaration with the NAM$B macro 
before ending it with a NAM$E macro. 

OPERATION MACRO - FAB OR RAB ADDRESS PARAMETER MISSING 

You must specify a control block address for the operation macro; 
for a file operation, specify a FAB address; for a stream, 
record, or block I/O operation, specify a RAB address. 

ORG$ MACRO - OPERATION PARAMETER INVALID 

You can specify only CRE, DEL, FIN, GET, PUT, and UPD as 
operation parameters for the ORG$ macro. 

ORG$ MACRO - ORGANIZATION PARAMETER INVALID 

You can specify only IDX, REL, or SEQ as the organization 
parameter for the ORG$ macro. 

ORG? MACRO - ORGANIZATION PARAMETER MISSING 

You must specify IDX, REL, or SEQ as the organization parameter 
for the ORG$ macro. 

POOL$B MACRO - ALREADY IN BLOCK OR POOL DECLARATION 

You cannot use the P0OL$B macro to begin pool declaration until 
you have ended the current block or pool declaration (using the 
FAB$E, NAM$E, POOL$E, RAB$E or XAB$E macro) . 

POOL$E MACRO - NOT IN POOL DECLARATION 

You must begin a POOL declaration with the POOL$B macro before 
ending it with a POOL$E macro. 

R$LSN MACRO - LSN FIELD NOT USED IN RMS-11 

RMS-11 has no LSN field in the RAB; therefore the R$LSN macro 
cannot initialize the field. 

RAB$B MACRO - ALREADY IN BLOCK OR POOL DECLARATION 

You cannot use the RAB$B macro to begin RAB declaration until you 
have ended the current block or pool declaration (using the 
FAB$E, NAM$E, POOL$E, RAB$E or XAB$E macro) . 
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RAB$B MACRO - RAB NOT WORD-ALIGNED 

Use the .EVEN assembler directive before the RAB$B macro; this 
assures word-alignment for the RAB. 

RAB$B MACRO - RAB TYPE PARAMETER INVALID 

You can specify only SYN, ASYN, or a null as the parameter for 
the RAB$B macro. 

RAB$E MACRO - NOT IN RAB DECLARATION 

You must begin a RAB declaration with the RAB$B macro before 
ending it with a RAB$E macro. 

X$SIZ MACRO - TOTAL KEY SIZE TOO LARGE 

The sum of the segment sizes for a key is greater than 255. 
Specify smaller segments. 

XAB$B MACRO - ALREADY IN BLOCK OR POOL DECLARATION 

You cannot use the XAB$B macro to begin XAB declaration until you 
have ended the current block or pool declaration (using the 
FAB$E, NAM$E, POOL$E, RAB$E or XAB$E macro). 

XAB$B MACRO - XAB NOT WORD-ALIGNED 

Use the .EVEN assembler directive before the XAB$B macro; this 
assures word-alignment for the XAB. 

XAB$B MACRO - XAB TYPE PARAMETER INVALID 

You can specify only XB$ALL, XB$DAT, XB$KEY, XB$PRO, or XB$SUM as 
the XAB type parameter for the XAB$B macro. 

XAB$E MACRO - NOT IN XAB DECLARATION 

You must begin a XAB declaration with the XAB$B macro before 
ending it with a XAB$E macro. 
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Table C-l lists RMS-11 macros (and their arguments) that declare 
symbols and other macros. In the table, the expression xxx represents 
a 2- or 3-character string, so that the expression 0$xxx represents 
all symbols that begin with 0$; the expression fid represents a field 
mnemonic. 

Note that you can declare symbols either globally or locally. For a 
FAB$BT, RAB$BT, XAB$BT, or $RMSTAT macro, give the argument DFIN$G (or 
omit the argument) to define symbols globally; give the argument 
DFIN$L to define symbols locally. 

Note also that you can declare symbols for control block sizes without 
declaring field-offset symbols. For a FABOF$, NAMOF$, RABOF$, XABOF$, 
XBAOF$, XBD0F$, XBK0F$, XBPOF$, or XBSOF$ macro, give the argument 
DEF$SZ to define only symbols for block sizes, or give no argument to 
define both symbols for block sizes and field-offset symbols. 

Table C-l: Macros That Declare Symbols and Other Macros 



Macro 



Argument Declares 



FAB$B 



FAB$BT 

FAB$BT 
FAB0F$ 

FABOF$ 



DFIN$G 



DFIN$L 



DEF$SZ 



- FAB field-initialization macros: of the form 
F$fld 

- FAB end-block-declaration macro: FAB$E 

- FAB field-offset symbols: of the form 0$fld 

- FAB code and mask symbols: of the form 
FB$xxx 

- Global FAB code and mask symbols: of the 
form FB$xxx (except FAB length symbol 
FB$BLN) 

- Local FAB code and mask symbols: of the form 
FB$xxx (except FAB length symbol FB$BLN) 

- FAB field offset symbols: of the form 0$fld 

- FAB length symbol: FB$BLN 

- FAB length symbol: FB$BLN 



(Continued on next page) 
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Table C-l (Cont.)J Macros That Declare Symbols and Other Macros 



Macro 



Argument Declares 



$FBCAL 



$GNCAL 



NAM$B 



NAMOF$ 

NAMOF$ 
POOL$B 

RAB$B 



- Directory operation macros: $ENTER, $PARSE, 
$REMOVE, $RENAME, and $SEARCH 

- File operation macros: $CLOSE, $CREATE, 
$DISPLAY, $ERASE, $EXTEND, and $OPEN 

- Get-space address macros: GSA$, $GETGSA, and 
$SETGSA 

- Facilities-declaration macro: ORG$ 

- RMS-11 initialization macros: $INIT and 
$INITIF (obsolete) 

- Field-access macros: $COMPARE, $FETCH, $OFF, 
$SET, $STORE, and $TESTBITS 

- Completion-handler return macro: $RETURN 

- NAM block field-initialization macros: of 
the form N$fld 

- NAM block end-block-declaration macro: NAM$E 

- NAM block field-offset symbols: of the form 
0$fld 

- NAM block code and mask symbols: of the form 
NB$xxx 

- NAM block field offset symbols: of the form 
0$fld 

- NAM block length symbol : NB$BLN 

DEF$SZ - NAM block length symbol: NB$BLN 

- Pool declaration macros: P$BDB, P$BUF, 
P$FAB, P$IDX, P$RAB, and P$RABX 

- End-pool-declaration macro: P00L$E 



- RAB field-initialization macros: of the form 
R$fld 

- RAB end-block-declaration macro: RAB$E 

- RAB field-offset symbols: of the form 0$fld 

- RAB code and mask symbols: of the form 
RB$xxx 

RAB$BT DFIN$G - Global RAB code and mask symbols: of the 

form RB$xxx (except RAB length symbol RB$BLN 
or RB$BLL) 

RAB$BT DFIN$L - Local RAB code and mask symbols: of the form 

RB$xxx (except RAB length symbol RB$BLN or 
RB$BLL) 

RABOF$ - RAB field offset symbols: of the form 0$fld 

- RAB length symbol: RB$BLN (for synchronous 
RAB) or RB$BLL (for asynchronous RAB) 

RABOF$ DEF$SZ - RAB length symbol: RB$BLN (for synchronous 

RAB) or RB$BLL (for asynchronous RAB) 



(Continued on next page; 
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Table C-l (Cont.) : Macros That Declare Symbols and Other Macros 



Macro 



Argument Declares 



$RBCAL 



$RMSTAT DFIN$G 



$RMSTAT DFIN$L 



XAB$B XB$ALL 



XAB$B XB$DAT 



XAB$B XB$KEY 



XAB$B XB$PRO 



XAB$B XB$SUM 



- Stream operation macros: $CONNECT, 
$DISCONNECT, $FLUSH, $FREE, $NXTVOL, 
$REWIND, and $WAIT 

- Record operation macros: $DELETE, $FIND, 
$GET, $PUT, $TRUNCATE, and $UPDATE 

- Block operation macros: $READ, $SPACE, and 
$WRITE 

- Global completion symbols: of the forms 
ER$xxx and SU$xxx 

- Local completion symbols: of the forms 
ER$xxx and SU$xxx 

- ALL block field-initialization macros: of 
the form X$fld 

- XAB end-block-declaration macro: XAB$E 

- ALL block field-offset symbols: of the form 
0$fld 

- XAB code and mask symbols : of the form 
XB$xxx 

- DAT block field-initialization macros: of 
the form X$fld 

- XAB end-block-declaration macro: XAB$E 

- DAT block field-offset symbols: of the form 
0$fld 

- XAB code and mask symbols: of the form 
XB$xxx 

- KEY block field-initialization macros: of 
the form X$fld 

- XAB end-block-declaration macro: XAB$E 

- KEY block field-offset symbols: of the form 
0$fld 

- XAB code and mask symbols: of the form 
XB$xxx 

- PRO block field-initialization macros: of 
the form X$fld 

- XAB end-block-declaration macro: XAB$E 

- PRO block field-offset symbols: of the form 
0$fld 

- XAB code and mask symbols: of the form 
XB$xxx 

- SUM block field-initialization macros: of 
the form X$fld 

- XAB end-block-declaration macro: XAB$E 

- SUM block field-offset symbols: of the form 
0$fld 

- XAB code and mask symbols : of the form 
XB$xxx 



(Continued on next page) 
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Table C-l (Cont.) : Macros That Declare Symbols and Other Macros 



Macro 



Argument Declares 



XAB$BT DFIN$G - Global XAB code and mask symbols: of the 

form XB$xxx (except XAB length symbols: 
XB$LAL, XB$DTL, XB$KYL, XB$PRL, and XB$SML) 

XAB$BT DFIN$L - Local XAB code and mask symbols: of the form 

XB$xxx (except XAB length symbols: XB$LAL, 
XB$DTL, XB$KYL, XB$PRL, and XB$SML) 

XABOF$ - XAB field offset symbols: of the form 0$fld 

- XAB length symbols: XB$LAL, XB$DTL, XB$KYL, 
XB$PRL, and XB$SML 

XAB0F$ DEF$SZ - XAB length symbols: XB$LAL, XB$DTL, XB$KYL, 

XB$PRL, and XB$SML 

XBA0F$ - ALL block field offset symbols: of the form 

0$fld 

- ALL block length symbol: XB$LAL 

XBA0F$ DEF$SZ - ALL block length symbol: XB$LAL 

XBD0F$ - DAT block field offset symbols: of the form 

OSfld 

- DAT block length symbol: XB$DTL 

XBDOF$ DEF$SZ - DAT block length symbol: XB$DTL 

XBKOF$ - KEY block field offset symbols: of the form 

0$fld 

- KEY block length symbol: XB$KYL 

XBKOF$ DEF$SZ - KEY block length symbol: XB$KYL 

XBP0F$ - PRO block field offset symbols: of the form 

0$fld 

- PRO block length symbol: XB$PRL 

XBPOF$ DEF$SZ - PRO block length symbol: XB$PRL 

XBSOF$ - SUM block field offset symbols: of the form 

0$fld 

- SUM block length symbol: XB$SML 

XBSOF$ DEF$SZ - SUM block length symbol: XB$SML 
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APPENDIX D 
RMS-11 WITH DIFFERENT OPERATING SYSTEMS 



This appendix contrasts the behaviors of RMS-11 on different operating 
systems: 

• PRO/RMS-11 versus RSTS/E RMS-11 

• PRO/RMS-11 versus RSX-11M/M-PLUS RMS-11 

• RSTS/E RMS-11 versus RSX-11M/MPLUS RMS-11 

D.l PRO/RMS-11 VERSOS RSTS/E RMS-11 

This section contrasts the behaviors of PRO/RMS-11 and RSTS/E RMS-11. 

D.l.l Different Behaviors 

The following features behave differently for RSTS/E and P/OS users: 

• Macro library location 

RMS-11 macro libraries for the systems are located in the 
files : 

RSTS/E LBtRMSMAC.MLB 

P/OS LB : [ 1 , 1 ] RMSMAC . MLB 

• RTV field in FAB 

The RTV field in the FAB has different uses: 

RSTS/E Cluster size 

p/OS Retrieval pointer count 

• Maximum bucket size 

The maximum bucket sizes (given by the BKS field in the FAB or 
the BKZ fields in ALL blocks) are different: 

RSTS/E 15 blocks 

p/OS 32 blocks 
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Area alignment 



The meanings of area alignment codes (in the ALN field of an 
ALL block) are different: 

RSTS/E XB$LBN Cluster alignment 

P/OS XB$CYL Cylinder alignment 

XB$LBN Logical block alignment 
XB$VBN Virtual block alignment 

Protection codes 

The protection codes (and defaults) are system-specific. 



D.1.2 Features Not Supported on RSTS/E 

The following RMS-11 features are not supported on RSTS/E, but are 
supported on P/OS: 

• ENTER operation ($ENTER macro) 

• NXTVOL operation ($NXTVOL macro) 

• REMOVE operation ($REMOVE macro) 

• SPACE operation ($SPACE macro) 

• WAIT operation ($WAIT macro) 

• User-provided interlocking (FB$UPI mask in SHR field of FAB) 

• File version numbers (NB$VER mask in FNB field of NAM) 

• Asynchronous execution of operations (RB$ASY mask in ROP field 
of RAB; SYN and ASYN arguments to RAB$B macro; RB$BLL symbol 
for length of asynchronous RAB) 

• Directories (DID field in NAM block) 

• Area extension (ALL block fields for $EXTEND macro) 

• Contiguous file extension (FB$CTG mask in FOP field of FAB for 
$EXTEND macro) 

• Hard placement (XB$HRD mask in AOP field of ALL block) 

• Return of date and protection information by DISPLAY operation 
(PRO block fields and DAT block fields for $DISPLAY macro) 

• File expiration date (EDT field of NAM block) and file 
revision number (RVN field of NAM block) 



D.1.3 Features Not Supported on P/OS 

On RSTS/E, for compatibility with older file system, RMS-11 treats 
certain sequential files with undefined records as sequential files 
with stream records. P/OS will allow only block access to such files. 
In addition, magtape devices are not supported on P/OS, and remote 
operations are not supported on P/OS. 
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D.2 PRO/RMS- 11 VERSUS RSX-11M/M-PLUS RMS-11 

The P/OS operating system does not support magtape devices or remote 
RMS-11 operations. 

P/OS files have decimal version numbers (NB$VER mask in FNB field of 
NAM) . 



D.3 RSTS/E RMS-11 VERSOS RSX-11M/M-PLUS RMS-11 

This section contrasts the behaviors of RSTS/E RMS-11 and 
RSX-11M/M-PLUS RMS-11. 



D.3.1 Different Behaviors 

The following features behave differently for RSTS/E and 
RSX-11M/M-PLUS users: 

• Macro library location 

RMS-11 macro libraries for the systems are located in the 
files : 

RSTS/E LB : RMSMAC . MLB 

RSX-11M/M-PLUS LB: [ 1, 1] RMSMAC .MLB 

• RTV field in FAB 

The RTV field in the FAB has different uses: 

RSTS/E Cluster size 

RSX-11M/M-PLUS Retrieval pointer count 

• Maximum bucket size 

The maximum bucket sizes (given by the BKS field in the FAB or 
the BKZ fields in ALL blocks) are different: 

RSTS/E 15 blocks 

RSX-11M/M-PLUS 32 blocks 

• Area alignment 

The meanings of area alignment codes (in the ALN field of an 
ALL block) are different: 

RSTS/E XB$LBN Cluster alignment 

RSX-11M/M-PLUS XB$CYL Cylinder alignment 

XB$LBN Logical block alignment 
XB$VBN Virtual block alignment 
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D.3.2 Features Not Supported on RSTS/E 

The following RMS-11 features are not supported on RSTS/E, but are 
supported on RSX-11M/M-PLUS: 

ENTER operation ($ENTER macro) 

• NXTVOL operation ($NXTVOL macro) 

• REMOVE operation ($REMOVE macro) 

• REWIND operation for magtape device ($REWIND macro) 

• SPACE operation ($SPACE macro) 

• WAIT operation ($WAIT macro) 

• User-provided interlocking (FB$UPI mask in SHR field of FAB) 

• Octal file version numbers (NB$VER mask in FNB field of NAM) 

• Asynchronous execution of operations (RB$ASY mask in ROP field 
of RAB; SYN and ASYN arguments to RAB$B macro; RB$BLL symbol 
for length of asynchronous RAB) 

• Directories (DID field in NAM block) 

• Area extension (ALL block fields for $EXTEND macro) 

• Contiguous file extension (FB$CTG mask in FOP field of FAB for 
$EXTEND macro) 

• Hard placement (XB$HRD mask in AOP field of ALL block) 

• Return of date and protection information by DISPLAY operation 
(PRO block fields and DAT block fields for $DISPLAY macro) 

• File expiration date (EDT field in NAM block) and file 
revision number (RVN field of NAM block) 

• Initial end-of-file context for magtape file (FB$NEF mask in 
FOP field of FAB for $OPEN macro) 

• Multivolume magtapes 
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$CLOSE macro, 5-3 
$COMPARE macro, 2-17 

example, 7-3, 7-7, 7-11, 7-15 
$CONNECT macro, 5-6 
$CREATE macro, 5-9 
$DELETE macro, 5-25 
$DISCONNECT macro, 5-27 
$DISPLAY macro, 5-29 

RSTS/E, D-4 
$ENTER macro, 5-35 

RSTS/E, D-4 
$ERASE macro, 5-40 

example, 7-11 
$EXTEND macro, 5-46 

RSTS/E, D-4 
$FBCAL macro, C-2 
$FETCH macro, 2-16 

example, 7-3, 7-7, 7-11, 7-15 
$FIND macro 

key access, 5-51 
RFA access, 5-54 
sequential access, 5-49 
$FLUSH macro, 5-56 
$FREE macro , 5-58 
$GET macro 

key access, 5-63 
RFA access, 5-67 
sequential access, 5-60 
$GETGSA macro, 2-21 
$GNCAL macro, C-2 
$INIT macro (obsolete) , xiv 
$INITIF macro (obsolete) , xiv 
$NXTVOL macro, 5-70 

RSTS/E, D-4 
$OFF macro, 2-12 
$OPEN macro, 5-72 

RSTS/E, D-4 
$PARSE macro, 5-86 

example, 7-3, 7-7, 7-11, 7-15 
$PUT macro 

key access, 5-95 
sequential access, 5-91 
$RBCAL macro, C-3 
$READ macro 

sequential access, 5-98 
VBN access, 5-100 
$REMOVE macro, 5-102 

RSTS/E, D-4 
$RENAME macro, 5-108 

example, 7-15 
$RETURN macro, 2-20 
$REWIND macro, 5-114 

RSTS/E magtape device, D-4 
$RLCB system routine, 2-22 
$RMSTAT macro, C-3 
$RQCB system routine, 2-22 
$SEARCH macro, 5-116 
example, 7-7, 7-15 
$SET macro, 2-12 
$SETGSA macro, 2-20 
$SPACE macro, 5-120 



RSTS/E, D-4 
$STORE macro, 2-11 

example, 7-3, 7-7, 7-11, 7-15 
$TESTBITS macro, 2-18 
$TRUNCATE macro, 5-122 
$UPDATE macro, 5-124 
$WAIT macro, 5-126 

RSTS/E, D-4 
$WRITE macro 

sequential access, 5-127 

VBN access, 5-129 
.EVEN assembler directive 

control block alignment, 2-8 

pool alignment, 2-4 
•MCALL assembler directive, 2-2 
/ML assembler switch, 2-22 

Access 

requested 

See FAC field in FAB 
shared 

See SHR field in FAB 
Access mode 
block 

See BKT field in RAB 
record 

See RAC field in RAB 
AID field in ALL block, 2-13 
CLOSE operation, 5-3 
CREATE operation, 5-9, 5-16 
DISPLAY operation, 5-30 
ENTER operation, 5-35 
ERASE operation, 5-40 
EXTEND operation, 5-46 to 5-47 
offset, 6-2 
OPEN operation, 5-73 
PARSE operation, 5-86 
REMOVE operation, 5-102 
RENAME operation, 5-108 
SEARCH operation, 5-116 
summary, 6-3 
Alignment 

See ALN field in ALL block 
ALL block 

chaining to FAB, 2-13 
declaring, 2-8 
initializing, 2-10 
summary, 6-2 
Allocation 

See ALQ field in ALL block 

See ALQ field in FAB 

XAB 

See ALL block 
ALN field in ALL block 
CREATE operation, 5-17 
DISPLAY operation, 5-30 
EXTEND operation, 5-47 
offset, 6-2 
OPEN operation, 5-79 
RSTS/E, D-4 
summary, 6-4 



Index-1 



INDEX 



ALQ field in ALL block 

CREATE operation, 5-16, 5-21 
DISPLAY operation, 5-30 
EXTEND operation, 5-47 
offset, 6-2 
OPEN operation, 5-79 
RSTS/E, D-4 
summary, 6-5 
ALQ field in FAB 

CREATE operation, 5-16, 5-21 
EXTEND operation, 5-46 to 5-47 
offset, 6-22 
OPEN operation, 5-78 
summary, 6-25 
ALQO field in ALL block 

offset, 6-2 
ALQ1 field in ALL block 

offset, 6-2 
ANSI magtape device, 3-2, 5-20, 
5-37, 5-43, 5-77, 5-88, 
5-104, 5-111, 5-118 
AOP field in ALL block 

CREATE operation, 5-17 to 5-18 

DISPLAY operation, 5-30 

EXTEND operation, 5-47 

offset, 6-2 

OPEN operation, 5-79 

RSTS/E, D-4 

summary 

XB$CTG mask, 6-6 

XB$HRD mask, 6-7 
Area 

alignment 

See ALN field in ALL block 
allocation 

See ALQ field in ALL block 
bucket size 

See BKZ field in ALL block 
contiguity 

See XB$CTG mask in AOP field 
count 

See NOA field in SUM block 
default extension size 

See DEQ field in ALL block 
description, obtaining 

See DISPLAY operation 
extending allocation 

See EXTEND operation 
identifier 

See AID field in ALL block 
location 

See LOC field in ALL block 
See ALL block 
Assembly, 2-22 

ASYN argument to RAB$B macro, 
2-8 

RSTS/E, D-4 
Asynchronous operation 
RAB declaration, 2-8 
See RB$ASY mask in ROP field 
waiting for 

See WAIT operation 

BDB pool, 2-8 
BID field in FAB 



offset, 6-22 

summary 

FB$BID code, 6-26 
BID field in RAB 

offset, 6-115 

summary 

RB$BID code, 6-116 
Binary key 

See XB$BN2 mask in DTP field 

See XB$BN4 mask in DTP field 
BKS field in FAB 

CREATE operation, 5-17 

offset, 6-24 

OPEN operation, 5-78 

RSTS/E, D-3 

summary, 6-27 
BKT field in RAB, 4-6, 

4-12 to 4-13 

FIND operation, 5-50, 5-52, 
5-55 

GET operation, 5-61, 5-65, 
5-68 

offset, 6-115 

PUT operation, 5-93, 5-96 

READ operation, 5-98, 5-100 

SPACE operation, 5-120 

summary, 6-117 

WRITE operation, 5-127, 5-129 
BKZ field in ALL block 

CREATE operation, 5-17 

DISPLAY operation, 5-30 

offset, 6-2 

OPEN operation, 5-79 

RSTS/E, D-3 to D-4 

summary, 6-8 
BLN field in ALL block 

offset, 6-2 

summary 

XB$LAL code, 6-9 
BLN field in DAT block 

offset, 6-14 

summary 

XB$DTL code, 6-15 
BLN field in FAB 

offset, 6-22 

summary 

FB$BLN code, 6-28 
BLN field in KEY block 

offset, 6-67 

summary 

XB$KYL code, 6-69 
BLN field in PRO block 

offset, 6-108 

summary 

XB$PRL code, 6-109 
BLN field in RAB 

offset, 6-115 

summary, 6-118 
BLN field in SUM block 

offset, 6-145 

summary 

XB$SML code, 6-146 
Block 

access mode 

See BKT field in RAB 
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locating 

See SPACE operation 

reading 

See READ operation 

size, magtape 

See BLS field in FAB 

writing 

See WRITE operation 
Block context, 4-12 
Block operation, 4-14 
Block operation macro 

$READ, 5-98, 5-100 

$SPACE, 5-120 

$WRITE, 5-127, 5-129 

declaring, C-3 
Block processing, 4-11 
Block stream, 4-11 
Block-declaration macro, 2-8, 

2-10 
Blocked record 

See FB$BLK mask in RAT field 
BLS field in FAB 

CREATE operation, 5-15 

offset, 6-24 

OPEN operation, 5-79 

summary, 6-29 
BPA field in FAB, 2-7, 3-5 

CLOSE operation, 5-4 

CREATE operation, 5-13 

ENTER operation, 5-36 

ERASE operation, 5-42 

offset, 6-24 

OPEN operation, 5-74 

PARSE operation, 5-87 

REMOVE operation, 5-104 

RENAME operation, 5-110 

SEARCH operation, 5-117 

summary, 6-30 
BPS field in FAB, 2-7, 3-5 

CLOSE operation, 5-4 

CREATE operation, 5-13 

ENTER operation, 5-36 

ERASE operation, 5-42 

offset, 6-24 

OPEN operation, 5-74 

PARSE operation, 5-87 

REMOVE operation, 5-104 

RENAME operation, 5-110 

SEARCH operation, 5-117 

summary, 6-31 
Bucket 

fill number 
data 

See DFL field in KEY block 
honoring 

See RB$LOA mask in ROP field 
index 

See IFL field in KEY block 

size 

See BKS field in FAB 
See BKZ field in ALL block 
Buffer 

record 

See RBF field in RAB 

user 



See UBF field in RAB 
Buffer pool, 3-5 

Call 

operation routine, 2-14 

arguments in memory, 2-15 
macro argument, 2-14 
Carriage control 

See RAT field in FAB 
Carriage-control device 

See FB$CCL mask in DEV field 
Carriage-return carriage control 

See FB$CR mask in RAT field 
Casette tape device, 3-2, 5-20, 
5-37, 5-43, 5-77, 5-88, 
5-104, 5-111, 5-118 
CDT field in DAT block 
DISPLAY operation, 5-32 
offset, 6-14 
OPEN operation, 5-81 
RSTS/E, D-4 
summary, 6-16 
Central buffer pool, 3-5 
Changed key 

See XB$CHG mask in FLG field 
CLOSE operation, 3-9 
$CLOSE macro, 5-3 
BDB requirement, 2-8 
I/O buffer requirement, 2-7 
wildcard loop, 3-11 
Cluster size 

See RTV field in FAB 
COD field in ALL block 
offset, 6-2 
summary 

XB$ALL code, 6-10 
COD field in DAT block 
offset, 6-14 
summary 

XB$DAT code, 6-17 ~^ 
COD field in KEY block 
offset, 6-67 
summary 

XB$KEY code, 6-70 
COD field in PRO block 
offset, 6-108 
summary 

XB$PRO code, 6-110 
COD field in SUM block 
offset, 6-145 
summary 

XB$SUM code, 6-147 
Code and mask symbol 
declaring 

ALL block, C-3 to C-4 
DAT block, C-3 to C-4 
FAB, C-l 

KEY block, C-3 to C-4 
NAM block, C-2 
PRO block, C-3 to C-4 
RAB, C-2 

SUM block, C-3 to C-4 
XAB, C-4 
value 

ALL block, 6-2 
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DAT block, 6-14 
FAB, 6-22 
KEY block, 6-67 
NAM block, 6-94 
PRO block, 6-108 
RAB, 6-115 
SUM block, 6-145 
Code symbol 

See Code and mask symbol 
Completion 

handler, 2-18 

return macro 
declaring, C-2 

symbol 

declaring, C-3 
Completion status 

See STS field in FAB 

See STS field in RAB 

See STV field in FAB 

See STV field in RAB 
CONNECT operation 

$CONNECT macro, 5-6 

BDB requirement, 2-8 

block stream, 4-13 

I/O buffer requirement, 2-7 

IRAB requirement, 2-5 

key buffer requirement, 2-6 

record stream, 4-8 
Context 

block stream, 4-12 

record stream, 4-3 
Contiguity 

See FB$CTG mask in FOP field 

See XB$CTG mask in AOP field 
Control block, 1-2 

chaining, 2-13 

declaring, 2-8 

examining, 2-16 

field 

See Field 

initializing, 2-8 

setting up, 2-11 
CRE argument to 0RG$ macro, 2-3 
CREATE operation, 3-8 

$CREATE macro, 5-9 

BDB requirement, 2-8 

declaring with ORG$ macro, 2-3 

I/O buffer requirement, 2-7 

IFAB requirement, 2-5 

wildcard loop, 3-11 
Creation date 

See CDT field in DAT block 
CTX field in FAB, 2-20 

offset, 6-22 

summary, 6-32 
CTX field in RAB, 2-20 

offset, 6-115 

summary, 6-119 
Current-record context, 4-3 

DAN field in KEY block 
CREATE operation, 5-19 
DISPLAY operation, 5-31 
offset, 6-67 
OPEN operation, 5-80 



summary, 6-71 
DAT block 

chaining to FAB, 2-13 to 2-14 

declaring, 2-8 

initializing, 2-10 

summary, 6-14 
Data area number 

See DAN field in KEY block 
Date 

See DAT block 

XAB 

See DAT block 
DBS field in KEY block 

DISPLAY operation, 5-31 

offset, 6-68 

OPEN operation, 5-80 

summary, 6-72 
DECtape device, 3-1, 5-20, 

5-37, 5-42, 5-77, 5-88, 

5-104, 5-111, 5-117 
DECTAPE II device, 3-1, 5-20, 

5-37, 5-42, 5-77, 5-88, 

5-104, 5-111, 5-117 
DEF$SZ argument, C-X 
Default extension fcize 

See DEQ field in ALL block 

See DEQ field in FAB 
Default string 

See DNA field in FAB 
Deferred writing 

See FB$DFW mask in FOP field 
DEL argument to ORG$ macro, 2-3 
DELETE operation, 4-11 

$DELETE macro, 5-25 

declaring with ORG$ macro, 2-3 
Deletion, file marked for 

See FB$MKD mask in FOP field 
DEQ field in ALL block 

CREATE operation, 5-17 

DISPLAY operation, 5-30 

offset, 6-2 

OPEN operation, 5-79 

RSTS/E, D-4 

summary, 6-11 
DEQ field in FAB 

CREATE operation, 5-17 

offset, 6-22 

OPEN operation, 5-74, 5-78 

summary, 6-33 
DEV field in FAB, 3-1 to 3-2 

CREATE operation, 5-20 

ENTER operation, 5-37 

ERASE operation, 5-42 to 5-43 

offset, 6-24 

OPEN operation, 5-77 

PARSE operation, 5-88 

REMOVE operation, 5-104 

RENAME operation, 5-111 

SEARCH operation, 
5-117 to 5-118 

summary, 6-34 
Device 

characteristics 

See DEV field in FAB 

identifier 
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See DVI field in NAM block 
DFIN$G argument, C-l 
DFIN$L argument, C-l 
DFL field in KEY block 
CREATE operation, 5-20 
DISPLAY operation, 5-31 
offset, 6-67 
OPEN operation, 5-80 
summary, 6-73 
DID field in NAM block 

CREATE operation, 5-10, 5-21 

ENTER operation, 5-36 to 5-37 

ERASE operation, 5-41 to 5-42 

offset, 6-94 

OPEN operation, 5-73, 5-77 

PARSE operation, 5-87 

REMOVE operation, 5-103, 5-105 

RENAME operation, 

5-109 to 5-111 
SEARCH operation, 5-116, 5-118 
summary, 6-95 
DID field in NAM block field 

RSTS/E, D-4 
Directory 

wildcard context 

See WDI field in NAM block 
wildcard operation 

See NB$WCH mask in FNB field 
Directory entry 
creating 

See ENTER operation 
deleting 

See REMOVE operation 
replacing 

See RENAME operation 
Directory operation, 3-5 
Directory operation macro 
$ENTER, 5-35 
$PARSE, 5-86 
$REMOVE, 5-102 
$RENAME, 5-108 
$SEARCH, 5-116 
declaring, C-2 
Directory processing, 3-1 
DISCONNECT operation 

$DISCONNECT macro, 5-27 
block stream, 4-14 
record stream, 4-9 
Disk device, 3-1, 5-20, 5-37, 
5-42, 5-77, 5-88, 5-104, 
5-111, 5-117 
DISPLAY operation, 3-8 
$DISPLAY macro, 5-29 
BDB requirement, 2-8 
I/O buffer requirement, 2-7 
wildcard loop, 3-11 
DNA field in FAB, 3-3 
CREATE operation, 5-10 
ENTER operation, 5-36 
ERASE operation, 5-41 
offset, 6-24 
OPEN operation, 5-73 
PARSE operation, 5-87 
REMOVE operation, 5-103 
RENAME operation, 



5-109 to 5-110 

summary, 6-35 
DNS field in FAB, 3-3 

CREATE operation, 5-10 

ENTER operation, 5-36 

ERASE operation, 5-41 

offset, 6-24 

OPEN operation, 5-73 

PARSE operation, 5-87 

REMOVE operation, 5-103 

RENAME operation, 
5-109 to 5-110 

summary, 6-36 
DTP field in KEY block 

CREATE operation, 5-18 

DISPLAY operation, 5-31 

offset, 6-67 

OPEN operation, 5-80 

summary, 6-74 
Duplicate key 

See XB$DUP mask in FLG field 
DVB field in KEY block 

DISPLAY operation, 5-31 

offset, 6-68 

OPEN operation, 5-80 

summary, 6-75 
DVI field in NAM block, 3-3 

CREATE operation, 5-10, 5-21 

ENTER operation, 5-36 to 5-37 

ERASE operation, 5-41 to 5-42 

offset, 6-94 

OPEN operation, 5-73, 5-77 

PARSE operation, 5-88 

REMOVE operation, 5-103, 5-105 

RENAME operation, 
5-109 to 5-111 

SEARCH operation, 5-116 

summary, 6-96 

EDT field in DAT block 

DISPLAY operation, 5-32 

offset, 6-14 

OPEN operation, 5-81 

summary, 6-18 
EDT field in NAM block 

RSX-11, D-4 
ENTER operation, 3-6 

$ENTER macro, 5-35 

BDB requirement, 2-8 

I/O buffer requirement, 2-7 

IFAB requirement, 2-5 

wildcard loop, 3-11 
ER$-family symbol 

declaring, C-3 

value, A-l to A-19 
ERASE operation, 3-8 

$ERASE macro, 5-40 

BDB requirement, 2-8 

I/O buffer requirement, 2-7 

IFAB requirement, 2-5 

wildcard loop, 3-10 to 3-11 
nonselective, 3-11 
selective, 3-12 
Error 

assembly-time, 2-22 
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fatal, 2-16 

handler, 2-18 
ESA field in NAM block, 3-3, 

3-10 

CREATE operation, 5-10 

ENTER operation, 5-36 

ERASE operation, 5-42 

offset, 6-94 

OPEN operation, 5-74 

PARSE operation, 5-87 

REMOVE operation, 5-104 

RENAME operation, 5-110 

SEARCH operation, 5-116 

summary, 6-97 
ESL field in NAM block 

CREATE operation, 5-21 

ENTER operation, 5-37 

ERASE operation, 5-42 

offset, 6-94 

OPEN operation, 5-77 

PARSE operation, 5-88 

REMOVE operation, 5-105 

RENAME operation, 5-111 

SEARCH operation, 5-116 

summary, 6-98 
ESS field in NAM block 

CREATE operation, 5-10 

ENTER operation, 5-36 

ERASE operation, 5-42 

offset, 6-94 

OPEN operation, 5-74 

PARSE operation, 5-87 

REMOVE operation, 5-104 

RENAME operation, 5-110 

summary, 6-99 
Expanded string 

See ESA field in NAM block 
EXTEND operation, 3-9 

$EXTEND macro, 5-46 

BDB requirement, 2-8 

I/O buffer requirement, 2-7 

wildcard loop, 3-11 
Extended attribute block 

See XAB 

F$-family macro, 2-10 

declaring, C-l 

example, 7-3, 7-7, 7-11, 7-15 
FAB 

chaining to RAB, 2-14 

declaring, 2-8 

initializing, 2-10 

summary, 6-22 
FAB field in RAB, 4-2 

chaining FAB to RAB, 2-14 

CONNECT operation, 5-6 

offset, 6-115 

summary, 6-120 
FAB$B macro, 2-8, C-l 

example, 7-3, 7-7, 7-11, 7-15 
FAB$BT macro, C-l 
FAB$E macro, 2-10 

declaring, C-l 

example, 7-3, 7-7, 7-11, 7-15 
FABOF$ macro, C-l 



FAC field in FAB 

CREATE operation, 5-14 

offset, 6-22 

OPEN operation, 5-75 

summary, 6-37 
Facilities-declaration macro, 

2-2 

declaring, C-2 
Fast deletion 

See RB$FDL mask in ROP field 
Fatal error, 2-16 
FB$-family symbol 

declaring, C-l 
FB$BID code in BID field 

summary, 6-26 

value, 6-22 
FB$BLK mask in RAT field 

CREATE operation, 5-11 

OPEN operation, 5-78 

summary, 6-60 

value, 6-23 
FB$BLN code in BLN field 

summary, 6-28 

value, 6-22 
FB$CCL mask in DEV field, 3-1 

CREATE operation, 5-20 

ENTER operation, 5-37 

ERASE operation, 5-42 

OPEN operation, 5-77 

PARSE operation, 5-88 

REMOVE operation, 5-104 

RENAME operation, 5-111 

SEARCH operation, 5-117 

value, 6-24 
FB$CR mask in RAT field 

CREATE operation, 5-12 

OPEN operation, 5-78 

value, 6-23 
FB$CTG mask in FOP field 

CREATE operation, 5-18 

EXTEND operation, 5-46 

OPEN operation, 5-78 

RSTS/E, D-4 

summary, 6-40 

value, 6-23 
FB$DEL mask in FAC field 

CREATE operation, 5-14 

OPEN operation, 5-75 

value, 6-22 
FB$DFW mask in FOP field 

CREATE operation, 5-15 

OPEN operation, 5-76 

summary, 6-41 

value, 6-23 
FB$DLK mask in FOP field 

CREATE operation, 5-15 

OPEN operation, 5-76 

summary, 6-42 

value, 6-23 
FB$FID mask in FOP field, 3-8, 

3-10 to 3-12 

CREATE operation, 5-10 

ENTER operation, 5-36 

ERASE operation, 5-41 

OPEN operation, 5-73 to 5-74 
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REMOVE operation, 5-103 
RENAME operation, 

5-109 to 5-110 
summary, 6-43 
value, 6-23 
FB$FIX code in RFM field 
CREATE operation, 5-11 
OPEN operation, 5-78 
value, 6-23 
FB$FTN mask in RAT field 
CREATE operation, 5-12 
OPEN operation, 5-78 
value, 6-23 
FB$GET mask in FAC field 
CREATE operation, 5-14 
OPEN operation, 5-75 
value, 6-22 
FB$GET mask in SHR field 
CREATE operation, 5-14 
OPEN operation, 5-75 
value, 6-22 
FB$IDX code in ORG field 
CREATE operation, 5-11 
OPEN operation, 5-78 
value, 6-23 
FB$MDI mask in DEV field, 3-1 
CREATE operation, 5-20 
ENTER operation, 5-37 
ERASE operation, 5-42 
OPEN operation, 5-77 
PARSE operation, 5-88 
REMOVE operation, 5-104 
RENAME operation, 5-111 
SEARCH operation, 5-117 
value, 6-24 
FB$MKD mask in FOP field 
CREATE operation, 5-11 
summary, 6-44 
value, 6-23 
FB$NEF mask in FOP field 
OPEN operation, 5-76 
RSTS/E, D-4 
summary, 6-45 
value, 6-23 
FB$NIL mask in SHR field 
CREATE operation, 5-14 
OPEN operation, 5-75 
value, 6-22 
FB$POS mask in FOP field 
CREATE operation, 5-15 
summary, 6-46 
value, 6-23 
FB$PRN mask in RAT field 
CREATE operation, 5-12 
OPEN operation, 5-78 
value, 6-23 
FB$PUT mask in FAC field 
CREATE operation, 5-14 
OPEN operation, 5-75 
value, 6-22 
FB$REA mask in FAC field 
CREATE operation, 5-14 
OPEN operation, 5-75 
value, 6-22 
FB$REC mask in DEV field. 



3-1 to 3-2 

CREATE operation, 5-20 

ENTER operation, 5-37 

ERASE operation, 5-42 to 5-43 

OPEN operation, 5-77 

PARSE operation, 5-88 

REMOVE operation, 5-104 

RENAME operation, 5-111 

SEARCH operation, 
5-117 to 5-118 

value, 6-24 
FB$REL code in ORG field 

CREATE operation, 5-11 

OPEN operation, 5-78 

value, 6-23 
FB$RWC mask in FOP field 

CLOSE operation, 5-4 

CREATE operation, 5-15 

OPEN operation, 5-77 

SEARCH operation, 5-117 

summary, 6-47 

value, 6-23 
FB$RWO mask in FOP field 

CREATE operation, 5-15 

OPEN operation, 5-76 
SEARCH operation, 5-117 
summary, 6-48 
value, 6-23 
FB$SDI mask in DEV field, 3-2 
CREATE operation, 5-20 
ENTER operation, 5-37 
ERASE operation, 5-43 
OPEN operation, 5-77 
PARSE operation, 5-88 
REMOVE operation, 5-104 
RENAME operation, 5-111 
SEARCH operation, 5-118 
value, 6-24 
FB$SEQ code in ORG field 
CREATE operation, 5-11 
OPEN operation, 5-78 
value, 6-23 
FB$SQD mask in DEV field, 3-2 
CREATE operation, 5-20 
ENTER operation, 5-37 
ERASE operation, 5-43 
OPEN operation, 5-77 
PARSE operation, 5-88 
REMOVE operation, 5-104 
RENAME operation, 5-111 
SEARCH operation, 5-118 
value, 6-24 
FB$STM code in RFM field 
CREATE operation, 5-11 
OPEN operation, 5-78 
value, 6-23 
FB$SUP mask in FOP field 
CREATE operation, 5-10 
summary, 6-49 
value, 6-23 
FB$TMD mask in FOP field 
CREATE operation, 5-11 
value, 6-23 
FB$TMP mask in FOP field 
CREATE operation, 5-11 
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summary, 6-50 

value, 6-23 
FB$TRM mask in DEV field, 3-1 

CREATE operation, 5-20 

ENTER operation, 5-37 

ERASE operation, 5-42 

OPEN operation, 5-77 

PARSE operation, 5-88 

REMOVE operation, 5-104 

RENAME operation, 5-111 

SEARCH operation, 5-117 

value, 6-24 
FB$TRN mask in FAC field 

CREATE operation, 5-14 

OPEN operation, 5-75 

value, 6-22 
FB$UDF code in RFM field 

CREATE operation, 5-11 

OPEN operation, 5-78 

value, 6-23 
FB$UPD mask in FAC field 

CREATE operation, 5-14 

OPEN operation, 5-75 

value, 6-22 
FB$UPI mask in SHR field 

CREATE operation, 5-14 

OPEN operation, 5-75 

value, 6-22 
FB$UPI mask in SHR field of FAB 

RSX-11, D-4 
FB$VAR code in RFM field 

CREATE operation, 5-11 

OPEN operation, 5-78 

value, 6-23 
FB$VFC code in RFM field 

CREATE operation, 5-11 

OPEN operation, 5-78 

value, 6-23 
FB$WRI mask in SHR field 

CREATE operation, 5-14 

OPEN operation, 5-75 

value, 6-22 
FB$WRT mask in FAC field 

CREATE operation, 5-14 

OPEN operation, 5-75 

value, 6-22 
FID field in NAM block 

CREATE operation, 5-21 

ENTER operation, 5-36 

ERASE operation, 5-41 to 5-42 

offset, 6-94 

OPEN operation, 5-73, 5-77 

REMOVE operation, 5-105 

RENAME operation, 5-111 

SEARCH operation, 5-118 

summary, 6-100 
Field, 1-2 

clearing bits in, 2-12 

comparing value, 2-17 

copying value from, 2-16 

copying value into, 2-11 

examining, 2-16 

initializing, 2-8 

mnemonic, 1-2 

setting bits in, 2-12 



setting up, 2-11 
testing bits in, 2-18 
Field-access macro 
$COMPARE, 2-17 
$FETCH, 2-16 
$OFF, 2-12 
$SET, 2-12 
$STORE, 2-11 
$TESTBITS, 2-18 
declaring, C-2 
Field-initialization macro, 2-10 
declaring 

ALL block, C-3 

DAT block, C-3 

FAB, C-l 

KEY block, C-3 

NAM block, C-2 

PRO block, C-3 

RAB, C-2 

SUM block, C-3 
Field-offset symbol 
declaring 

ALL block, C-3 to C-4 

DAT block, C-3 to C-4 

FAB, C-l 

KEY block, C-3 to C-4 

NAM block, C-2 

PRO block, C-3 to C-4 

RAB, C-2 

SUM block, C-3 to C-4 

XAB, C-4 
value 

ALL block, 6-2 

DAT block, 6-14 

FAB, 6-22 

KEY block, 6-67 

NAM block, 6-94 

PRO block, 6-108 

RAB, 6-115 

SUM block, 6-145 
File 

access requested 

See FAC field in FAB 
access shared 

See SHR field in FAB 
alignment 

See ALN field in ALL block 
allocation 

See ALQ field in ALL block 

See ALQ field in FAB 
area 

See ALL block 
bucket size 

See BKS field in FAB 

See BKZ field in ALL block 
closing 

See CLOSE operation 
cluster size 

See RTV field in FAB 
contiguity 

See FB$CTG mask in FOP field 

See XB$CTG mask in AOP field 
creating 

See CREATE operation 
creation date 
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See CDT field in DAT block 
date 

See DAT block 
default extension size 

See DEQ field in ALL block 

See DEQ field in FAB 
deleting 

See ERASE operation 
extending allocation 

See EXTEND operation 
identifier 

See FID field in NAM block 
internal file identifier 

See IFI field in FAB 
location 

See LOC field in ALL block 
locking 

See FB$DLK mask in FOP field 
name block 

See NAM block 
opening 

See OPEN operation 
organization 

See ORG field in FAB 
owner 

See PRG field in PRO block 
protection 

See PRO field in PRO block 
record-output characteristic 

See RAT field in FAB 
renaming 

See RENAME operation 
revision date 

See RDT field in DAT block 
revision number 

See RVN field in DAT block 
specification string 

default 

See DNA field in FAB 

parsing 

See FNB field in NAM block 

See FNA field in FAB 
string 

See FNA field in FAB 
supersession 

See FB$SUP mask in FOP field 
truncating 

See TRUNCATE operation 
wildcard context 

See WCC field in NAM block 
wildcard operation 

See NB$WCH mask in FNB field 
wildcard search 

See SEARCH operation 
File access block 

See FAB 
File operation, 3-7 
File operation macro 
$CLOSE, 5-3 
$CREATE, 5-9 
$DISPLAY, 5-29 
$ERASE, 5-40 
$EXTEND, 5-46 
$0PEN, 5-72 
declaring, C-2 



File processing, 3-1 
File specification 
fully qualified, 3-4 
merged string, 3-3 
parsing 

See PARSE operation 
wildcard, 3-9 
Fill number 
data bucket 

See DFL field in KEY block 
index bucket 

See IFL field in KEY block 
FIN argument to ORG$ macro, 2-3 
FIND operation, 4-10 
$FIND macro 

key access, 5-51 
RFA access, 5-54 
sequential access, 5-49 
declaring with ORG$ macro, 2-3 
Fixed-control -size 

See FSZ field in FAB 
Fixed-length record format 

See FB$FIX code in RFM field 
FLG field in KEY block 
CREATE operation, 5-19 
DISPLAY operation, 5-31 
offset, 6-67 
OPEN operation, 5-80 
summary 

XB$CHG mask, 6-76 
XB$DUP mask, 6-77 
XB$NUL mask, 6-78 
FLUSH operation 

$FLUSH macro, 5-56 
record stream, 4-8 
FNA field in FAB, 3-3 
CREATE operation, 5-10 
ENTER operation, 5-36 
ERASE operation, 5-41 
offset, 6-24 
OPEN operation, 5-73 
PARSE operation, 5-87 
REMOVE operation, 5-103 
RENAME operation, 

5-109 to 5-110 
summary, 6-38 
FNB field in NAM block, 3-3, 
3-10 to 3-11 
CREATE operation, 5-21 
ENTER operation, 5-37 to 5-38 
ERASE operation, 5-41, 5-43 
offset, 6-94 
OPEN operation, 5-81 
PARSE operation, 5-88 
REMOVE operation, 5-103, 5-105 
RENAME operation, 5-109, 

5-111 to 5-112 
SEARCH operation, 5-116, 5-118 
summary, 6-101 

NB$WCH mask, 6-102 
wildcard loop, 3-11 
FNS field in FAB, 3-3 
CREATE operation, 5-10 
ENTER operation, 5-36 
ERASE operation, 5-41 
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5-73 

5-87 
, 5-103 



3-8, 
5-4 

5-15, 5-18 

5-36 

5-41 
, 5-46 

5-73 to 5-74, 

, 5-103 

i 

, 5-117 



offset, 6-24 
OPEN operation, 
PARSE operation, 
REMOVE operation 
RENAME operation 
5-109 to 5-110 
summary, 6-39 
FOP field in FAB, 
3-10 to 3-12 
CLOSE operation, 
CREATE operation 

5-10 to 5-11, 
ENTER operation, 
ERASE operation, 
EXTEND operation 
offset, 6-23 
OPEN operation, 

5-76 to 5-78 
REMOVE operation 
RENAME operation 
5-109 to 5-110 
SEARCH operation 
summary 

FB$CTG mask, 6 
FB$DFW mask, 6 
FB$DLK mask, 6 
FB$FID mask, 6 
FB$MKD mask, 6 
FB$NEF mask, 6 
FB$POS mask, 6 
FB$RWC mask, 6 
FB$RWO mask, 6 
FB$SUP mask, 6 
FB$TMP mask, 6 
FORTRAN-style carr 

See FB$FTN mask 
FREE operation 
$FREE macro, 5-5 
block stream, 4- 
record stream, 4 
Free-space list fo 
FSZ field in FAB 
CREATE operation 
offset, 6-24 
OPEN operation, 
summary, 6-51 



GET argument to ORG$ macro, 2-3 
GET operation, 4-10 
$GET macro 

key access, 5-63 
RFA access, 5-67 
sequential access, 5-60 
declaring with ORG$ macro, 2-3 
Get-space routine, 2-20 
example, 7-18 
macro 

declaring, C-2 
RMS-11-supplied, 2-4 
GSA$ macro, 2-20 

example, 7-3, 7-7, 7-11, 7-15 

Hard location 

See XB$HRD mask in AOP field 
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2-21 


, 5-11 




5-78 





I/O buffer pool, 2-6 
IAN field in KEY block 

CREATE operation, 5-19 

DISPLAY operation, 5-31 

offset, 6-67 

OPEN operation, 5-80 

summary, 6-79 
IBS field in KEY block 

DISPLAY operation, 5-31 

offset, 6-68 

OPEN operation, 5-80 

summary, 6-80 
IDB pool, 2-5 

IDX argument to ORG$ macro, 2-3 
IFAB pool, 2-5 
IFI field in FAB 

CLOSE operation, 5-3 to 5-4 

CONNECT operation, 5-6 

CREATE operation, 5-20 

DISPLAY operation, 5-30 

EXTEND operation, 5-46 

offset, 6-22 

OPEN operation, 5-77 

summary, 6-52 
IFL field in KEY block 

CREATE operation, 5-20 

DISPLAY operation, 5-31 

offset, 6-67 

OPEN operation, 5-80 

summary, 6-81 
Index 

area bucket size 

See IBS field in KEY block 

area number 
higher levels 

See IAN field in KEY block 
lowest level 

See LAN field in KEY block 

count 

See NOK field in SUM block 

data bucket size 

See DBS field in KEY block 

data bucket VBN 

See DVB field in KEY block 

description, obtaining 
See DISPLAY operation 

level count 

See LVL field in KEY block 

reference number 

See REF field in KEY block 

root bucket VBN 

See RVB field in KEY block 

See KEY block 
Indexed file 

declaring with ORG$ macro, 2-3 
Indexed file organization 

See FB$IDX code 
Initialization 

field, 2-10 
Integer key 

See XB$IN2 mask in DTP field 

See XB$IN4 mask in DTP field 
Internal file identifier 

See IFI field in FAB 
Internal stream identifier 
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See ISI field in RAB 

IRAB pool, 2-5 

ISI field in RAB, 4-2 
CONNECT operation, 5-7 
DELETE operation, 5-25 
DISCONNECT operation, 5-27 
FIND operation, 5-49, 5-51, 

5-54 
FLUSH operation, 5-56 
FREE operation, 5-58 
GET operation, 5-60, 5-63, 

5-67 
NXTVOL operation, 5-70 
offset, 6-115 
PUT operation, 5-91, 5-95 
READ operation, 5-98, 5-100 
REWIND operation, 5-114 
SPACE operation, 5-120 
summary, 6-121 
TRUNCATE operation, 5-122 
UPDATE operation, 5-124 
WAIT operation, 5-126 
WRITE operation, 5-127, 5-129 

KBF field in RAB, 4-5 
FIND operation, 5-52 
GET operation, 5-63 
offset, 6-115 
PUT operation, 5-96 
summary, 6-122 
Key 

buffer address 

See KBF field in RAB 
buffer size 

See KSZ field in RAB 
changes 

See XB$CHG mask in FLG field 
characteristics 

See FLG field in KEY block 
data type 

See DTP field in KEY block 
duplication 

See XB$DUP mask in FLG field 
match criterion 

See RB$KGE mask in ROP field 
See RB$KGT mask in ROP field 
name 

See KNM field in KEY block 
null character 

See NUL field in KEY block 
reference 

See KRF field in RAB 
segment 
position 

See POS field in KEY block 
size 

See SIZ field in KEY block 
segment count 

See NSG field in KEY block 
size, total 

See TKS field in KEY block 
XAB 

See KEY block 
KEY block 

chaining to FAB, 2-13 to 2-14 



declaring, 2-8 

initializing, 2-10 

summary, 6-67 
Key buffer pool, 2-6 
Key record access 

See RB$KEY code in RAC field 
KNM field in KEY block 

CREATE operation, 5-18 

DISPLAY operation, 5-30 

offset, 6-68 

OPEN operation, 5-74 

summary, 6-82 
KRF field in RAB, 4-5 

CONNECT operation, 5-7 

FIND operation, 5-51 

GET operation, 5-63 

offset, 6-115 

REWIND operation, 5-114 

summary, 6-123 
KSZ field, in RAB, 4-5 to 4-6 

FIND operation, 5-52 

GET operation, 5-63 

offset, 6-115 

PUT operation, 5-96 

summary, 6-124 

LAN field in KEY block 
CREATE operation, 5-19 

DISPLAY operation, 5-31 

offset, 6-67 

OPEN operation, 5-80 

summary, 6-83 
LCH field in FAB, 3-2 

CREATE operation, 5-13 

ENTER operation, 5-36 

ERASE operation, 5-42 

offset, 6-24 

OPEN operation, 5-74 

PARSE operation, 5-87 

REMOVE operation, 5-104 

RENAME operation, 5-110 

SEARCH operation, 5-117 

summary, 6-53 
LOC field in ALL block 

CREATE operation, 5-17 

EXTEND operation, 5-47 

offset, 6-2 

RSTS/E, D-4 

summary, 6-12 
LOCO field in ALL block 

offset, 6-2 
LOCI field in ALL block 

offset, 6-2 
Locate mode 

See RB$LOC mask in ROP field 
Location 

hard 

See XB$HRD mask in AOP field 

See LOC field in ALL block 
Locking, file 

See FB$DLK mask in FOP field 
Logical channel number 

See LCH field in FAB 
LRL field in FAB 

CREATE operation, 5-20 
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offset, 6-24 
OPEN operation, 5-79 
summary, 6-54 
LVL field in KEY block 
DISPLAY operation, 5-32 
offset, 6-67 
OPEN operation, 5-80 
summary, 6-84 

Macro library 

RMSMAC.MLB, 2-22 

RSTS/E, D-3 
Macro-declaration macro, 2 
Magtape 

positioning 

See FB$NEF mask in FOP 
See FB$POS mask in FOP 
See RB$EOF mask in ROP 

rewind-after -closing 
See FB$RWC mask in FOP 

rewind-before-creating 
See FB$RWO mask in FOP 

rewind -before-opening 
See FB$RWO mask in FOP 
Magtape block size 

See BLS field in FAB 
Magtape device, 3-2, 5-20, 

5-37, 5-43, 5-77, 5-88, 

5-104, 5-111, 5-118 

ANSI, 3-2, 5-20, 5-37, 5 
5-77, 5-88, 5-104, 5-1 
5-118 

P/OS, D-3 
Mark-for-deletion 

See FB$MKD mask in FOP f 
Mask symbol 

See Code and mask symbol 
Mass insertion 

See RB$MAS mask in ROP f 
Match criterion 

See RB$KGE mask in ROP f 

See RB$KGT mask in ROP f 
MBC field in RAB 

CONNECT operation, 5-6 

offset, 6-115 

summary, 6-125 
MBF field in RAB 

CONNECT operation, 5-6 

offset, 6-115 

summary, 6-126 
Merged string, 3-3 
MRL field in KEY block 

DISPLAY operation, 5-32 

offset, 6-68 

OPEN operation, 5-80 

summary, 6-85 
MRN field in FAB 

CREATE operation, 5-13 

offset, 6-24 

OPEN operation, 5-79 

summary, 6-55 
MRS field in FAB 

CREATE operation, 5-12 

offset, 6-24 

OPEN operation, 5-79 



field 
field 
field 

field 

field 

field 



-43, 
11, 



ield 



ield 

ield 
ield 



summary, 6-56 
Multiblock count 

See MBC field in RAB 
Multibuffer count 

See MBF field in RAB 
Multidirectory device 

See FB$MDI mask in DEV field 

N$-family macro, 2-10 

declaring, C-2 

example, 7-3, 7-7, 
NAM block 

chaining to FAB, 2- 

declaring, 2-8 

identification by 
See FB$FID mask i 

initializing, 2-10 

summary, 6-94 
NAM field in FAB 

chaining NAM block 
2-13 

CREATE operation, 5 

ENTER operation, 5- 

ERASE operation, 5- 

offset, 6-24 

OPEN operation, 5-7 

PARSE operation, 5- 

REMOVE operation, 5 

RENAME operation, 5 

SEARCH operation, 5 

summary, 6-57 
NAM$B macro, 2-8, C-2 

example, 7-3, 7-7, 
NAM$E macro, 2-10 

declaring, C-2 

example, 7-3, 7-7, 
NAMOF$ macro, C-2 
NB$-family symbol 

declaring, C-2 
NB$DEV mask in FNB fi 

CREATE operation, 5 

ENTER operation, 5- 

ERASE operation, 5- 

OPEN operation, 5-8 

PARSE operation, 5- 

REMOVE operation, 5 

RENAME operation, 5 

value, 6-94 
NB$DIR mask' in FNB fi 

CREATE operation, 5 

ENTER operation, 5- 

ERASE operation, 5- 

OPEN operation, 5-8 

PARSE operation, 5- 

REMOVE operation, 5 

RENAME operation, 5 

value, 6-94 
NB$NAM mask in FNB fi 

CREATE operation, 5 

ENTER operation, 5- 

ERASE operation, 5- 

OPEN operation, 5-8 

PARSE operation 
(set if NB$QUO is 

REMOVE operation, 5 
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RENAME operation, 5-111 

value, 6-94 
NB$NOD mask in FNB field 

CREATE operation, 5-21 

ENTER operation, 5-37 

ERASE operation, 5-43 

OPEN operation, 5-81 

PARSE operation, 5-88 

REMOVE operation, 5-105 

RENAME operation, 5-111 

value, 6-94 
NB$QUO mask in FNB field 

CREATE operation, 5-21 

ENTER operation, 5-37 

ERASE operation, 5-43 

OPEN operation, 5-81 

PARSE operation, 5-88 

REMOVE operation, 5-105 

RENAME operation, 5-111 

value, 6-94 
NB$TYP mask in FNB field 

CREATE operation, 5-21 

ENTER operation, 5-37 

ERASE operation, 5-43 

OPEN operation, 5-81 

PARSE operation 

(set if NB$QUO is set), 5-88 

REMOVE operation, 5-105 

RENAME operation, 5-111 

value, 6-94 
NB$VER mask in FNB field 

CREATE operation, 5-21 

ENTER operation, 5-37 

ERASE operation, 5-43 

OPEN operation, 5-81 

PARSE operation, 5-88 

REMOVE operation, 5-105 

RENAME operation, 5-111 

value, 6-94 
NB$VER mask in FNB field of NAM 

RSX-11, D-3 to D-4 
NB$WCH mask in FNB field, 

3-10 to 3-11 

CREATE operation, 5-21 

ENTER operation, 5-38 

ERASE operation, 5-41, 5-43 

OPEN operation, 5-81 

PARSE operation, 5-88 

REMOVE operation, 5-103, 5-105 

RENAME operation, 5-109, 5-112 

SEARCH operation, 5-116, 5-118 

summary, 6-102 

value, 6-94 

wildcard loop, 3-11 
NB$WDI mask in FNB field 

CREATE operation, 5-21 

ENTER operation, 5-37 

ERASE operation, 5-43 

OPEN operation, 5-81 

PARSE operation, 5-88 

REMOVE operation, 5-105 

RENAME operation, 5-111 

value, 6-94 
NB$WNA mask in FNB field 

CREATE operation, 5-21 



ENTER operation, 5-37 
ERASE operation, 5-43 
OPEN operation, 5-81 
PARSE operation, 5-88 
REMOVE operation, 5-105 
RENAME operation, 5-111 
value, 6-94 

NB$WTY mask in FNB field 
CREATE operation, 5-21 
ENTER operation, 5-37 
ERASE operation, 5-43 
OPEN operation, 5-81 
PARSE operation, 5-88 
REMOVE operation, 5-105 
RENAME operation, 5-111 
value, 6-94 

NB$WVE mask in FNB field 
CREATE operation, 5-21 
ENTER operation, 5-37 
ERASE operation, 5-43 
OPEN operation, 5-81 
PARSE operation, 5-88 
REMOVE operation, 5-105 
RENAME operation, 5-111 
value, 6-94 

Next-record context, 4-3 

NOA field in SUM block 
DISPLAY operation, 5-32 
offset, 6-145 
OPEN operation, 5-81 
summary, 6-148 

NOK field in SUM block 
DISPLAY operation, 5-32 
offset, 6-145 
OPEN operation, 5-81 
summary, 6-149 

NSG field in KEY block 
DISPLAY operation, 5-31 
offset, 6-68 
OPEN operation, 5-81 
summary, 6-86 

NUL field in KEY block 
CREATE operation, 5-19 
DISPLAY operation, 5-31 
offset, 6-67 
OPEN operation, 5-80 
summary, 6-87 

Null key character 

See NUL field in KEY block 
See XB$NUL mask in FLG field 

NXT field in ALL block 
CLOSE operation, 5-3 
CREATE operation, 5-9 
DISPLAY operation, 5-30 
ENTER operation, 5-35 
ERASE operation, 5-40 
EXTEND operation, 5-46 
offset, 6-2 
OPEN operation, 5-73 
PARSE operation, 5-86 
REMOVE operation, 5-102 
RENAME operation, 5-108 
SEARCH operation, 5-116 
summary, 6-13 

NXT field in DAT block 
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CLOSE operation, 
CREATE operation, 
DISPLAY operation 
ENTER operation, 
ERASE operation, 
EXTEND operation, 
offset, 6-14 
OPEN operation, 5 
PARSE operation, 
REMOVE operation, 
rename operation, 
SEARCH operation, 
summary, 6-19 

NXT field in KEY bl 
CLOSE operation, 
CREATE operation, 
DISPLAY operation 
ENTER operation, 
ERASE operation, 
EXTEND operation, 
offset, 6-67 
OPEN operation, 5 
PARSE operation, 
REMOVE operation, 
RENAME operation, 
SEARCH operation, 
summary, 6-88 

NXT field in PRO bl 
CLOSE operation, 
CREATE operation, 
DISPLAY operation 
ENTER operation, 
ERASE operation, 
EXTEND operation, 
offset, 6-108 
OPEN operation, 5 
PARSE operation, 
REMOVE operation, 
RENAME operation, 
SEARCH operation, 
summary, 6-111 

NXT field in SUM bl 
CLOSE operation, 
CREATE operation, 
DISPLAY operation 
ENTER operation, 
ERASE operation, 
EXTEND operation, 
offset, 6-145 
OPEN operation, 5 
PARSE operation, 
REMOVE operation, 
RENAME operation, 
SEARCH operation, 
summary, 6-150 

NXT field in XAB 
chaining XABs to 

NXTVOL operation 
$NXTVOL macro, 5- 
record stream, 4- 
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FAB, 2-13 

70 
9 



6-2 
6-14 



6-108 



6-145 



6-68 



0$-family symbol 
declaring 

ALL block, C-3 to C-4 
DAT block, C-3 to C-4 



FAB field offset, C-l 

KEY block, C-3 to C-4 

NAM block field offset, C-2 

PRO block, C-3 to C-4 

RAB, C-2 

SUM block, C-3 to C-4 

XAB, C-4 
value 

ALL block, 

DAT block, 

FAB, 6-22 to 6-24 

KEY block, 6-67 to 

NAM block, 6-94 

PRO block, 

RAB, 6-115 

SUM block, 
OPEN operation, 3-8 
$OPEN macro, 5-72 
BDB requirement, 2-8 
I/O buffer requirement, 2-7 
IFAB requirement, 2-5 
wildcard loop, 3-11 to 3-12 
Operation, 1-2 
routine 

calling, 2-14 

return, 2-15 
using, 2-10 
Operation macro, 1-2, 2-10 
ORG field in FAB 

CREATE operation, 5-11 
offset, 6-23 
OPEN operation, 5-78 
summary, 6-58 
ORG? macro, 2-2 
Organization, file 

See ORG field in FAB 
Owner, file 

See PRG field in PRO block 

P$-family macro 

declaring, C-2 
P$BDB macro 

argument computation, 2-8 

format, 2-4 
P$BUF macro 

argument computation, 2-7 

format, 2-4 
P$FAB macro 

argument computation, 2-5 

format, 2-4 
P$IDX macro 

argument computation, 2-5 

format, 2-4 
P$RAB macro 

argument computation, 2-5 

format, 2-4 
P$RABX macro 

argument computation, 
2-5 to 2-6 

format, 2-4 
Packed decimal key 

See XB$PAC mask in DTP field 
PARSE operation, 3-6 

$PARSE macro, 5-86 

BDB requirement, 2-8 
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I/O buffer requirement, 2-7 
IFAB requirement, 2-5 
wildcard initialization, 3-10 
Pool 

buffer descriptor block, 2-8 
declaring space, 2-4 
free-space list, 2-21 
I/O buffer, 2-6 
index descriptor block, 2-5 
internal FAB, 2-5 
internal RAB, 2-5 
key buffer, 2-6 
See also Get-space routine 
POOL$B macro, 2-4, C-2 
POOL$E macro, 2-4 

declaring, C-2 
Pool-declaration macro, 2-4 

declaring, C-2 
POS field in KEY block 
CREATE operation, 5-18 
DISPLAY operation, 5-31 
offset, 6-68 
OPEN operation, 5-80 
summary, 6-89 
POS0 field in KEY block 

offset, 6-68 
POS1 field in KEY block 

offset, 6-68 
POS2 field in KEY block 

offset, 6-68 
POS3 field in KEY block 

offset, 6-68 
POS4 field in KEY block 

offset, 6-68 
POS5 field in KEY block 

offset, 6-68 
POS6 field in KEY block 

offset, 6-68 
POS7 field in KEY block 

offset, 6-68 
Positioning 
magtape 

See FB$NEF mask in FOP field 
See FB$POS mask in FOP field 
PRG field in PRO block 
CLOSE operation, 5-3 
DISPLAY operation, 5-32 
offset, 6-108 
OPEN operation, 5-81 
RSTS/E, D-4 
summary, 6-112 
Printer device, 3-1, 5-20, 
5-37, 5-42, 5-77, 5-88, 
5-104, 5-111, 5-117 
Private buffer pool 
See BPA field in FAB 
See BPS field in FAB 
PRJ field in PRO block 
CLOSE operation, 5-3 
DISPLAY operation, 5-32 
offset, 6-108 
OPEN operation, 5-81 
RSTS/E, D-4 
summary, 6-113 
PRO block 



chaining to FAB, 2-13 to 2-14 

declaring, 2-9 

initializing, 2-10 

summary, 6-108 
PRO field in PRO block 

CLOSE operation, 5-3 

CREATE operation, 5-11 

DISPLAY operation, 5-32 

offset, 6-108 

OPEN operation, 5-81 

RSTS/E, D-4 

summary, 6-114 
PRO/RMS- 11 

contrasted with RSTS/E RMS-11, 
D-l 

contrasted with RSX-11 RMS-11, 
D-3 
Prologue version number 

See PVN field in SUM block 
Protection 

file 

See PRO field in PRO block 

XAB 

See PRO block 
PUT argument to ORG$ macro, 2-3 
PUT operation, 4-10 

$PUT macro 

key access, 5-95 
sequential access, 5-91 

declaring with ORG$ macro, 2-3 
PVN field in SUM block 

DISPLAY operation, 5-32 

offset, 6-145 

OPEN operation, 5-81 

summary, 6-151 

R$-family macro, 2-10 

declaring, C-2 
RAB 

declaring, 2-8 

initializing, 2-10 

summary, 6-115 
RAB$B macro, 2-8, C-2 
RAB$BT macro, C-2 
RAB$E macro, 2-10 

declaring, C-2 
RABOF$ macro, C-2 
RAC field in RAB, 4-4 to 4-6 

FIND operation, 5-49, 5-51, 
5-54 

GET operation, 5-60, 5-63, 
5-67 

offset, 6-115 

PUT operation, 5-91, 5-95 

summary, 6-127 
RAT field in FAB 

CREATE operation, 5-11 to 5-12 

offset, 6-23 

OPEN operation, 5-78 

summary, 6-59 

FB$BLK mask, 6-60 
RB$-family symbol 

declaring, C-2 
RB$ASY mask in ROP field, 4-1 

CONNECT operation, 5-7 
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DELETE operation, 5-25 

DISCONNECT operation, 5-27 

FIND operation, 5-49, 5-51, 
5-54 

FLUSH operation, 5-56 

FREE operation, 5-58 

GET operation, 5-60, 5-63, 
5-67 

NXTVOL operation, 5-70 

PUT operation, 5-91, 5-95 

READ operation, 5-98, 5-100 

REWIND operation, 5-114 

RSTS/E, D-4 

SPACE operation, 5-120 

summary, 6-131 

TRUNCATE operation, 5-122 

UPDATE operation, 5-124 

value, 6-115 

WRITE operation, 5-127, 5-129 
RB$BID code in BID field 

summary, 6-116 

value, 6-115 
RB$BLL code in BLN field 

RSTS/E, D-4 

value, 6-115 
RB$BLN code in BLN field 

value, 6-115 
RB$EOF mask in ROP field 

CONNECT operation, 5-7 

summary, 6-132 

value, 6-115 
RB$FDL mask in ROP field 

DELETE operation, 5-25 

summary, 6-133 

value, 6-115 
RB$KEY code in RAC field, 4-5 

FIND operation, 5-51 

GET operation, 5-63 

PUT operation, 5-95 

value, 6-115 
RB$KGE mask in ROP field, 

4-5 to 4-6 

FIND operation, 5-52 

GET operation, 5-64 

summary, 6-134 

value, 6-115 
RB$KGT mask in ROP field, 

4-5 to 4-6 

FIND operation, 5-52 

GET operation, 5-64 

summary, 6-135 

value, 6-115 
RB$LOA mask in ROP field 

PUT operation, 5-92, 5-96 

summary, 6-136 

UPDATE operation, 5-124 

value, 6-115 
RB$LOC mask in ROP field, 4-7 

CONNECT operation, 5-6 

GET operation, 5-61, 5-64, 
5-68 

PUT operation, 5-92 

summary, 6-137 

value, 6-115 
RB$MAS mask in ROP field 



PUT operation, 5-92 
summary, 6-138 
value, 6-115 
RB$RFA code in RAC field, 4-6 
FIND operation, 5-54 
GET operation, 5-67 
value, 6-115 
RB$SEQ code in RAC field, 4-4 
FIND operation, 5-49 
GET operation, 5-60 
PUT operation, 5-91 
value, 6-115 
RB$UIF mask in ROP field, 4-4 
PUT operation, 5-92, 5-96 
summary, 6-139 
value, 6-115 
RBF field in RAB, 4-7, 4-13 
CONNECT operation, 5-7 
GET operation, 5-61, 5-65, 

5-68 
offset, 6-115 
PUT operation, 5-92 to 5-93, 

5-95 
READ operation, 5-99, 5-101 
summary, 6-128 
UPDATE operation, 5-124 
WRITE operation, 5-127, 5-129 
RDT field in DAT block 
DISPLAY operation, 5-32 
offset, 6-14 
OPEN operation, 5-81 
RSTS/E, D-4 
summary, 6-20 
READ operation, 4-14 
$READ macro 

sequential access, 5-98 

VBN access, 5-100 
Readable-block context, 4-12 
Record 

access mode 

See RAC field in RAB 
blocked 

See FB$BLK mask in RAT field 
buffer address 

See RBF field in RAB 
deleting 

fast 

See RB$FDL mask in ROP field 

See DELETE operation 
fast deletion 

See RB$FDL mask in ROP field 
format 

See RFM field in FAB 
locating 

See FIND operation 
longest 

See LRL field in FAB 
reading 

See GET operation 
replacing 

See UPDATE operation 
size 

See RSZ field in RAB 
update existing 

See RB$UIF mask in ROP field 
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writing 

See PUT operation 
Record access block 

See RAB field in RAB 
Record access mode, 4-4 
Record context, 4-3 
Record file address 

See RFA field in RAB 
Record length 
longest 

See LRL field in FAB 
maximum 

See MRL field in FAB 
Record number 
maximum 

See MRN field in FAB 
Record operation, 4-9 
Record operation macro 
$DELETE, 5-25 
$FIND, 5-49, 5-51, 5-54 
$GET, 5-60, 5-63, 5-67 
$PUT, 5-91, 5-95 
$TRUNCATE, 5-122 
$UPDATE, 5-124 
declaring, C-3 
Record processing, 4-3 
Record stream, 4-3 
Record-oriented device 

See FB$REC mask in DEV field 
Record-output characteristic 

See RAT field in FAB 
REF field in KEY block, 2-14 
CLOSE operation, 5-3 
CREATE operation, 5-9, 5-18 
DISPLAY operation, 5-30 
ENTER operation, 5-35 
ERASE operation, 5-40 
EXTEND operation, 5-46 
offset, 6-67 

OPEN operation, 5-73 to 5-74 
PARSE operation, 5-86 
REMOVE operation, 5-102 
RENAME operation, 5-108 
SEARCH operation, 5-116 
summary, 6-90 
REL argument to ORG$ macro, 2-3 
Relative file 

declaring with ORG$ macro, 2-3 
Relative file organization 

See FB$REL code 
Relative record number 
See BKT field in RAB 
Remote operation 

P/OS, D-3 
REMOVE operation, 3-6 
$REMOVE macro, 5-102 
BDB requirement, 2-8 
I/O buffer requirement, 2-7 
IFAB requirement, 2-5 
wildcard loop, 3-10 to 3-11 
nonselective, 3-11 
selective, 3-12 
RENAME operation, 3-6 
$RENAME macro, 5-108 
BDB requirement, 2-8 



I/O buffer requirement, 2-7 

IFAB requirement, 2-5 
wildcard loop, 3-10 to 3-11 
nonselective, 3-11 
selective, 3-12 
Resultant string 

See RSA field in NAM block 
Retrieval pointer count 

See RTV field in FAB 
Return 

operation, from, 2-15 
Return from completion handler, 

2-20 
Revision date 

See RDT field in DAT block 
Revision number 

See RVN field in DAT block 
REWIND operation 

$REWIND macro, 5-114 

record stream, 4-9 
RFA field in RAB, 4-6 

CONNECT operation, 5-7 

FIND operation, 5-50, 5-52, 
5-54 

GET operation, 5-61, 5-65, 
5-67 

offset, 6-115 

PUT operation, 5-93, 5-96 

READ operation, 5-99, 5-101 

summary, 6-129 

WRITE operation, 5-128, 5-130 
RFA record access 

See RB$RFA code in RAC field 
RFM field in FAB 

CREATE operation, 5-11 

offset, 6-23 

OPEN operation, 5-78 

summary, 6-61 
RHB field in RAB, 4-7 

GET operation, 5-61, 5-64, 
5-68 

offset, 6-115 

PUT operation, 5-92, 5-96 

summary, 6-130 

UPDATE operation, 5-124 
RMSMAC.MLB macro library, 2-22 

RSTS/E, D-3 
ROP field in RAB, 4-1, 

4-4 to 4-7 

CONNECT operation, 5-6 to 5-7 

DELETE operation, 5-25 

DISCONNECT operation, 5-27 

FIND operation, 5-49, 
5-51 to 5-52, 5-54 

FLUSH operation, 5-56 

FREE operation, 5-58 

GET operation, 5-60 to 5-61, 
5-63 to 5-64, 5-67 to 5-68 

NXTVOL operation, 5-70 

offset, 6-115 

PUT operation, 5-91 to 5-92, 
5-95 to 5-96 

READ operation, 5-98, 5-100 

REWIND operation, 5-114 

SPACE operation, 5-120 
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summary 

RB$ASY mask, 6-131 

RB$EOF mask, 6-132 

RB$FDL mask, 6-133 

RB$KGE mask, 6-134 

RB$KGT mask, 6-135 

RB$LOA mask, 6-136 

RB$LOC mask, 6-137 

RB$MAS mask, 6-138 

RB$UIF mask, 6-139 
TRUNCATE operation, 5-122 
UPDATE operation, 5-124 
WRITE operation, 5-127, 5-129 
RRN 

See BKT field in RAB 
RSA field in NAM block, 3-10 
offset, 6-94 
SEARCH operation, 5-116 
summary, 6-103 
RSL field in NAM block 
CREATE operation, 5-21 
ENTER operation, 5-38 
ERASE operation, 5-43 
offset, 6-94 
OPEN operation, 5-81 
PARSE operation, 5-87 
REMOVE operation, 5-105 
RENAME operation, 5-112 
SEARCH operation, 

5-116 to 5-117 
summary, 6-104 
RSS field in NAM block 
offset, 6-94 
SEARCH operation, 5-116 
summary, 6-105 
RSTS/E RMS-11 

contrasted with PRO/RMS-11, 

D-l 
contrasted with RSX-11 RMS-11, 

D-3 
RSX-11M/M-PLUS RMS-11 

contrasted with PRO/RMS-11, 

D-3 
contrasted with RSTS/E RMS-11, 

D-3 
RSZ field in RAB, 4-7, 4-13 
GET operation, 5-61, 5-65, 

5-68 
offset, 6-115 
PUT operation, 5-92, 5-95 
READ operation, 5-99, 5-101 
summary, 6-140 
UPDATE operation, 5-124 
WRITE operation, 5-127, 5-129 
RTV field in FAB 

CREATE operation, 5^13 
offset, 6-23 
OPEN operation, 5-75 
RSTS/E, D-3 
summary, 6-62 
RVB field in KEY block 
DISPLAY operation, 5-31 
offset, 6-68 
OPEN operation, 5-80 
summary, 6-91 



RVN field in DAT block 

DISPLAY operation, 5-32 

offset, 6-14 

OPEN operation, 5-81 

RSTS/E, D-4 

summary, 6-21 
RVN field in NAM block ' 

RSX-11, D-4 

SEARCH operation 

$SEARCH macro, 5-116 

BDB requirement, 2-8 

I/O buffer requirement, 2-7 

IFAB requirement, 2-5 

wildcard loop, 3-10 
explicit, 3-12 
implicit, 3-10 to 3-11 
SEQ argument to ORG$ macro, 2-3 
Sequential block access 

See BKT field in RAB 
Sequential device 

See FB$SQD mask in DEV field 
Sequential file 

declaring with ORG$ macro, 2-3 
Sequential file organization 

See FB$SEQ code 
Sequential record access 

See RB$SEQ code in RAC field 
Shared access 

See SHR field in FAB 
SHR field in FAB 

CREATE operation, 5-14 

offset, 6-22 

OPEN operation, 5-75 

READ operation, 5-99, 5-101 

summary, 6-63 

WRITE operation, 5-127, 5-129 
Single-directory device 

See FB$SDI mask in DEV field 
SIZ field in KEY block 

CREATE operation, 5-18 

DISPLAY operation, 5-31 

offset, 6-68 

OPEN operation, 5-80 

summary, 6-92 
SIZ0 field in KEY block 

offset, 6-68 
SIZ1 field in KEY block 

offset, 6-68 
SIZ2 field in KEY block 

offset, 6-68 
SIZ3 field in KEY block 

offset, 6-68 
SIZ4 field in KEY block 

offset, 6-68 
SIZ5 field in KEY block 

offset, 6-68 
SIZ6 field in KEY block 

offset, 6-68 
SIZ7 field in KEY block 

offset, 6-68 
SPACE operation, 4-14 

$SPACE macro, 5-120 
Stream, 4-2 

connecting 
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See CONNECT operation 
disconnecting 

See DISCONNECT operation 
internal identifier 

See ISI field in RAB 
unlocking bucket 

See FREE operation 
writing buffers 

See FLUSH operation 
Stream context 

advancing to next volume 

See NXTVOL operation 
rewinding 

See REWIND operation 
Stream operation 
block stream, 4-13 
record stream, 4-8 
Stream operation macro 
$CONNECT, 5-6 
$DISCONNECT, 5-27 
$FLUSH, 5-56 
$FREE, 5-58 
$NXTVOL, 5-70 
$REWIND, 5-114 
$WAIT, 5-126 
declaring, C-3 
Stream record format 

See FB$STM code in RFM field 
String key 

See XB$STG mask in DTP field 
STS field in FAB, 2-15, 3-5 
CLOSE operation, 5-4 
CREATE operation, 5-21 
DISPLAY operation, 5-32 
ENTER operation, 5-38 
ERASE operation, 5-43 
EXTEND operation, 5-47 
offset, 6-22 
OPEN operation, 5-82 
PARSE operation, 5-89 
REMOVE operation, 5-105 
RENAME operation, 5-112 
SEARCH operation, 5-118 
summary, 6-64 
STS field in RAB, 2-15, 4-2 
CONNECT operation, 5-8 
DELETE operation, 5-26 
DISCONNECT operation, 5-27 
FIND operation, 5-50, 5-53, 

5-55 
FLUSH operation, 5-56 
FREE operation, 5-58 
GET operation, 5-62, 5-65, 

5-68 
NXTVOL operation, 5-70 
offset, 6-115 
PUT operation, 5-93, 5-97 
READ operation, 5-99, 5-101 
REWIND operation, 5-115 
SPACE operation, 5-120 
summary, 6-141 
TRUNCATE operation, 5-122 
UPDATE operation, 5-125 
WRITE operation, 5-128, 5-130 
STV field in FAB, 2-15, 3-5 



CLOSE operation, 5-4 

CREATE operation, 5-21 

DISPLAY operation, 5-32 

ENTER operation, 5-38 

ERASE operation, 5-43 

EXTEND operation, 5-47 

offset, 6-22 

OPEN operation, 5-82 

PARSE operation, 5-89 

REMOVE operation, 5-105 

RENAME operation, 5-112 

SEARCH operation, 5-118 

summary, 6-65 
STV field in RAB, 2-15, 4-2 

CONNECT operation, 5-8 

DELETE operation, 5-26 

DISCONNECT operation, 5-27 

FIND operation, 5-50, 5-53, 
5-55 

FLUSH operation, 5-56 

FREE operation, 5-58 

GET operation, 5-62, 5-65, 
5-68 

NXTVOL operation, 5-70 

offset, 6-115 

PUT operation, 5-93, 5-97 

READ operation, 5-99, 5-101 

REWIND operation, 5-115 

SPACE operation, 5-120 

summary, 6-142 

TRUNCATE operation, 5-122 

UPDATE operation, 5-125 

WRITE operation, 5-128, 5-130 
SU$-family symbol 

declaring, C-3 

value, A-l 
Success 

handler, 2-18 
SUM block 

chaining to FAB, 2-13 

declaring, 2-9 

initializing, 2^10 

summary, 6-145 
Summary XAB 

See SUM block 
Supersession 

See FB$SUP mask in FOP field 
Symbol-declaration macro, 2-2 
SYN argument to RAB$B macro, 2-8 

RSTS/E, D-4 
Synchronous operation 

See RB$ASY mask in ROP field 

Temporary file 

See FB$TMP mask in FOP field 
Terminal device, 3-1, 5-20, 

5-37, 5-42, 5-77, 5-88, 

5-104, 5-111, 5-117 

See FB$TRM mask in DEV field 
TKS field in KEY block 

DISPLAY operation, 5-31 

offset, 6-68 

OPEN operation, 5-81 

summary, 6-93 
TRUNCATE operation, 4-11 
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$TRUNCATE macro, 5-122 

UBF field in RAB, 4-7, 4-13 

CONNECT operation, 5-6 

GET operation, 5-61, 5-64, 
5-67 

offset, 6-115 

PUT operation, 5-92, 5-96 

READ operation, 5-98, 5-100 

summary, 6-143 
Undefined record format 

See FB$UDF code in RFM field 
Unit-record device, 3-2, 5-20, 

5-37, 5-43, 5-77, 5-88, 

5-104, 5-111, 5-117 
UPD argument to 0RG$ macro, 2-3 
UPDATE operation, 4-11 

$UPDATE macro, 5-124 

declaring with ORG$ macro, 2-3 
User buffer 

address 

See UBF field in RAB 

si ze 

See USZ field in RAB 
USZ field in RAB, 4-7, 4-13 

CONNECT operation, 5-6 

GET operation, 5-61, 5-64, 
5-67 

offset, 6-115 

PUT operation, 5-92, 5-96 

READ operation, 5-98, 5-100 

summary, 6-144 

Variable-length record format 

See FB$VAR code in RFM field 
VBN 

See BKT field in RAB 
VBN access 

See BKT field in RAB 
VFC carriage control 

See FB$PRN mask in RAT field 
VFC header buffer address 

See RHB field in RAB 
VFC record format 

See FB$VFC code in RFM field 
Virtual block number 

See BKT field in RAB 
Volume 

advancing to next 

See NXTVOL operation 

WAIT operation 

$WAIT macro, 5-126 

block stream, 4-14 

record stream, 4-9 
WCC field in NAM block 

offset, 6-94 

PARSE operation, 5-87 

SEARCH operation, 5-116, 5-118 

summary, 6-106 
WDI field in NAM block 

offset, 6-94 

PARSE operation, 5-87 

SEARCH operation, 5-116, 5-118 

summary, 6-107 



Wildcard 

directory context 

See WDI field in NAM block 
file context 

See WCC field in NAM block 
operation 

See NB$WCH mask in FNB field 
Wildcard loop, 3-9 
Writable-block context, 4-12 
WRITE operation, 4-14 
$WRITE macro 

sequential access, 5-127 
VBN access, 5-129 

X$-family macro, 2-10 
declaring 

ALL block, C-3 
DAT block, C-3 
KEY block, C-3 
PRO block, C-3 
SUM block, C-3 
XAB 

chaining to FAB, 
See also ALL bloc 
See also DAT bloc 
See also KEY bloc 
See also PRO bloc 
See also SUM bloc 
XAB field in FAB 
chaining XABs to 
CLOSE operation, 
CREATE operation, 
DISPLAY operation 
ENTER operation, 
ERASE operation, 
EXTEND operation, 
offset, 6-24 
OPEN operation, 5 
PARSE operation, 
REMOVE operation, 
RENAME operation, 
SEARCH operation, 
summary, 6-66 
XAB$B macro, 2-8 to 
XAB$BT macro, C-4 
XAB$E macro, 2-10 

declaring, C-3 
XABOF$ macro, C-4 
XB$-family symbol 
declaring 

ALL block, C-3 
DAT block, C-3 
KEY block, C-3 
PRO block, C-3 
SUM block, C-3 
XAB, C-4 
XB$ALL code in COD 
summary, 6-10 
value, 6-2 
XB$BN2 code in DTP 
CREATE operation, 
DISPLAY operation 
OPEN operation, 5 
value, 6-67 
XB$BN4 code in DTP field 
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CREATE operation, 5-18 

DISPLAY operation, 5-31 

OPEN operation, 5-80 

value, 6-67 
XB$CHG mask in FLG field 

CREATE operation, 5-19 

DISPLAY operation, 5-31 

OPEN operation, 5-80 

summary, 6-76 

value, 6-67 
XB$CTG mask in AOP field 

CREATE operation, 5-18 

EXTEND operation, 5-47 

OPEN operation, 5-79 

RSTS/E, D-4 

summary, 6-6 

value, 6-2 
XB$CYL mask in ALN field 

RSTS/E, D-3 to D-4 
XB$DAT code in COD field, 2-8 

summary, 6-17 

value, 6-14 
XB$DTL code in BLN field 

summary, 6-15 

value, 6-14 
XB$DUP mask in FLG field 

CREATE operation, 5-19 

DISPLAY operation, 5-31 

OPEN operation, 5-80 

summary, 6-77 

value, 6-67 
XB$HRD mask in AOP field 

CREATE operation, 5-17 

EXTEND operation, 5-47 

of ALL block 
RSX-11, D-4 

OPEN operation, 5-79 

RSTS/E, D-4 

summary, 6-7 

value, 6-2 
XB$IN2 code in DTP field 

CREATE operation, 5-18 

DISPLAY operation, 5-31 

OPEN operation, 5-80 

value, 6-67 
XB$IN4 code in DTP field 

CREATE operation, 5-18 

DISPLAY operation, 5-31 

OPEN operation, 5-80 

value, 6-67 
XB$INI mask in FLG field 

DISPLAY operation, 5-31 

OPEN operation, 5-80 

value, 6-67 
XB$KEY code in COD field, 2-8 

summary, 6-70 

value, 6-67 
XB$KYL code in BLN field 

summary, 6-69 

value, 6-67 
XB$LAL code in BLN field 

summary, 6-9 

value, 6-2 
XB$LBN mask in ALN field 

CREATE operation, 5-17 



EXTEND operation, 
RSTS/E, D-3 to D- 
value, 6-2 

XB$NUL mask in FLG 
CREATE operation, 
DISPLAY operation 
OPEN operation, 5 
summary, 6-78 
value, 6-67 

XB$PAC code in DTP 
CREATE operation, 
DISPLAY operation 
OPEN operation, 5 
value, 6-67 

XB$PRL code in BLN 
summary, 6-109 
value, 6-108 

XB$PRO code in COD 
summary, 6-110 
value, 6-108 

XB$SML code in BLN 
summary, 6-146 
value, 6-145 

XB$STG code in DTP 
CREATE operation, 
DISPLAY operation 
OPEN operation, 5 
value, 6-67 

XB$SUM code in COD 
summary, 6-147 
value, 6-145 

XB$VBN mask in ALN 
CREATE operation, 
EXTEND operation, 
RSTS/E, D-3 to D- 
value, 6-2 

XBAOF$ macro, C-4 

XBDOF$ macro, C-4 

XBKOF$ macro, C-4 

XBP0F$ macro, C-4 

XBSOF$ macro, C-4 
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